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

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

In this tutorial, you learn how to:

  • Create a VNET in Azure using Azure CLI
  • Create a secure Service Fabric cluster in Azure using Azure CLI
  • Secure the cluster with an X.509 certificate
  • Connect to the cluster using Service Fabric CLI
  • 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 deploys 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. 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 Linux cluster is deployed with the following characteristics:

  • a single node type
  • five nodes in the primary node type (configurable in the template parameters)
  • OS: Ubuntu 16.04 LTS (configurable in the template parameters)
  • certificate secured (configurable in the template parameters)
  • 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 setup for the following ports:

  • client connection endpoint: 19000
  • HTTP gateway endpoint: 19080
  • application port: 80
  • application port: 443

Virtual network and subnet

The names of the virtual network and subnet 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: 10.0.0.0/16
  • Service Fabric subnet address space: 10.0.2.0/24

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

Set template parameters

The AzureDeploy.Parameters 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.
adminPassword Password#1234 Admin password for the cluster VMs.
clusterName mysfcluster123 Name of the cluster.
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 a subnet 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 az sf cluster create command and template to deploy a new cluster secured with an existing certificate. The command also creates a new key vault in Azure and uploads your certificate.

ResourceGroupName="sflinuxclustergroup"
Location="southcentralus"
Password="q6D7nN%6ck@6"
VaultName="linuxclusterkeyvault"
VaultGroupName="linuxclusterkeyvaultgroup"
CertPath="C:\MyCertificates\MyCertificate.pem"

# sign in to your Azure account and select your subscription
az login
az account set --subscription <guid>

# Create a new resource group for your deployment and give it a name and a location.
az group create --name $ResourceGroupName --location $Location

# Create the Service Fabric cluster.
az sf cluster create --resource-group $ResourceGroupName --location $Location \
   --certificate-password $Password --certificate-file $CertPath \
   --vault-name $VaultName --vault-resource-group $ResourceGroupName  \
   --template-file AzureDeploy.json --parameter-file AzureDeploy.Parameters.json

Create a cluster using a new, self-signed certificate

The following script uses the az sf cluster create command and a template to deploy a new cluster in Azure. The cmcommand also creates a new key vault in Azure, adds a new self-signed certificate to the key vault, and downloads the certificate file locally.

ResourceGroupName="sflinuxclustergroup"
ClusterName="sflinuxcluster"
Location="southcentralus"
Password="q6D7nN%6ck@6"
VaultName="linuxclusterkeyvault"
VaultGroupName="linuxclusterkeyvaultgroup"
CertPath="C:\MyCertificates"

az sf cluster create --resource-group $ResourceGroupName --location $Location --cluster-name $ClusterName --template-file C:\temp\cluster\AzureDeploy.json --parameter-file C:\temp\cluster\AzureDeploy.Parameters.json --certificate-password $Password --certificate-output-folder $CertPath --certificate-subject-name $ClusterName.$Location.cloudapp.azure.com --vault-name $VaultName --vault-resource-group $ResourceGroupName

Connect to the secure cluster

Connect to the cluster using the Service Fabric CLI command sfctl cluster select with your key. Note, only use the --no-verify option for a self-signed certificate.

sfctl cluster select --endpoint https://aztestcluster.southcentralus.cloudapp.azure.com:19080 \
--pem ./aztestcluster201709151446.pem --no-verify

Check that you are connected and the cluster is healthy using the sfctl cluster health command.

sfctl cluster health

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 Azure CLI
  • Create a secure Service Fabric cluster in Azure using Azure CLI
  • Secure the cluster with an X.509 certificate
  • Connect to the cluster using Service Fabric CLI
  • Remove a cluster

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