First, We need to set up the infrastructure:
- Servers: Request Server Team to set up at least 3 servers which installed Window server
2016. The best practice from Microsoft is 5 servers. However, more or less depends on your company
- Network: Request Network Team to set up the NLB on top of 3 servers. Recommend to
create a new subnet for this cluster if possible
- DNS: Apply the DNS for the cluster and servers. Highly recommended because we will use the
servers and cluster FQDN in the Service Fabric configuration instead of IP Address. This allows to
changes in server IP without re-build the cluster.
- Certificates: The cluster should be trusted by a Certificate Authority (CA) server. The
Service Fabric is working fine with self-signed certificate however for security purpose we should use
the trusted certificates instead
- Service account: Normally all the servers in the enterprise system will be connected to an
AD. For SF installation we also need a service account as Admin of all servers. Here, I created SFAdmin
and add it into Administrations group of all 3 servers.
After finishing the setup the infrastructure should look like below which:
- SS.hbd.net is my cluster FQDN pointing to the NLB.
- SS1.hbd.net is server 1 FQDN.
- SS2.hbd.net is server 2 FQDN.
- SS3.hbd.net is server 3 FQDN.
- HBD-CA: The CA server, all certificates are generated by this server.
2. Create Certificates
Next, There are a few certificates required to be applied to all servers before installing the SF cluster:
- Cluster certificate: which protect the entire cluster and explorer.
- Server certificate: which protect the communication between the nodes.
- Reverse proxy certificate: which allows reverse proxy serving the HTTPS protocol.
- Admin Certificate: which allows connecting to the cluster as Administration role. This
will be used for deployment as well
- User Certificate: which allows connecting to the cluster as a Read-only role.
In this topic, I will generate a single certificate for Cluster, Server and Reverse proxy and the other two for
Admin and the Read-only client accessing roles. So totally, I need to generate 3 certificates:
- Cert 1:
- Subject: CN=sf.hbd.net
- Thumbprint: 21 ce 44 e7 49 5c ee 56 9b 11 f5 88 27 e3 b8 23 b9 29 7f f7
- Cert 2:
- Subject: CN=sfclientadmin.hbd.net
- Thumbprint: 38 22 69 8e 91 90 a2 27 7e 20 21 02 ad 5d 8f 16 e4 dd 5a 7a
- Cert 3:
- Subject: CN=sfclient.hbd.net
- Thumbprint: 5c c9 d0 66 ef 9c 89 52 85 8b 35 b1 f9 6c 77 66 a8 5d 01 3c
Don’t know how to generate custom certificates from a CA server? Check out the topic here
for Generating the certificates with custom options.
3. Install Certificate to the servers
After generating the certificates we need to install them on the 3 servers above and grant the read permission
to NETWORK SERVICE account as Service Fabric is using this account for installation and
Instead of manually install every certificate on every server and then grant the access to the service accounts.
I have developed a small script which allows to import all certs and grant the permission to service accounts
at the same time.
Download PowerShell script here
into the same folder with PFX files and update the variables accordingly:
# The folder of pfx files. all certs in the folder will be imported.
$certLocation = ".\*.pfx";
#Specify the password of the pfx files.
$certPass = "SF";
# Specify the Service account that the cert will be granted to. It should be NETWORK SERVICE as SF is using this account for installation and running.
$serviceAccount= "NETWORK SERVICE";
# The store of certs. The default is Cert:\LocalMachine\My. You can changes to the other store if requires for some reason.
$CertStoreLocation = "Cert:\LocalMachine\My";
Login to the servers with the service account (SFAdmin), copy the whole into Download folder and then
run the script with Administration privilege.
All the certs should be installed and able to verify again via MMC we need to ensure the certs had been imported
4. Download The Service Fabric installer
- Download the Service Standalone package here
and extract to a folder ex: SFInstall
- Download the Service Fabric Runtime here
to the SFInstall folder above if installing on the offline servers.
- Copy SFInstall to Download folder in 1 of 3 servers which will be used to the SF cluster.
Here, I copied to the server SS1.
In SFInstall folder open the ClusterConfig.X509.MultiMachine.json file and apply the below
- Server config:
Under the nodes section, filling up the server information as below.
- Certificate config:
Config the security section with certificates information generated above. Ensure the Cluster and
Server credential type isX509.
"metadata": "The Credential type X509",
The CertificateIssuerThumbprint is the thumbprint of a trusted certificate from CA server which
is generated automatically when the server connected to a CA server. Here is my trusted issuer certificate is
Alternatively, you can remove the CertificateIssuerThumbprint from all sections above and add the CertificateIssuerStores
as below config in under the ReverseProxyCertificateCommonNames section.
After this steps, the credential configuration is done. If you wish to review a whole configuration then refer here
The recommendation, before executing the installation we should verify the config file against to the best
practices recommended by Microsoft by using below command. This command not only verifies the config file but
also verify the prerequisite on all the servers mentioned in the config file.
.\TestConfiguration.ps1 -ClusterConfigFilePath ./ClusterConfig.X509.MultiMachine.json -FabricRuntimePackagePath ./MicrosoftAzureServiceFabric.cab
Ensure the command is pointing to the correct installer file MicrosoftAzureServiceFabric.cab
If everything fine the result should be as below.
Installation: finally we are in the most important step of the topic, the installation step.
However, this is also the simplest step as just execute the below command. The installer will install the
Service Fabric runtime on to all servers and bring the cluster within a few minutes.
.\CreateServiceFabricCluster.ps1 -ClusterConfigFilePath ./ClusterConfig.X509.MultiMachine.json -FabricRuntimePackagePath ./MicrosoftAzureServiceFabric.cab -AcceptEULA
Finally, The installation is done and the Service Fabric cluster is up.
- From a terminal PC, Import the sfclientadmin and sfclient certificates to current user store.
- Open Chrome and login to SF cluster. There is a popup which allows selecting the certificate.
- If login with the sfclientadmin certificate you will able to restart, deactivate and activate the node.
However, the sfclient will give you read-only permission which you can view all the applications, nodes
- Review the Reverse proxy setting on the Explorer you will see that it is supporting the HTTPS protocol
which allows you to host and access the https endpoint.
IV. Uninstall SF Cluster
Similar to installation, To uninstall the SF cluster you run the below command. It will uninstall all the SF
instance from all servers in the cluster based on the JSON configuration.
.\RemoveServiceFabricCluster -ClusterConfigFilePath ./ClusterConfig.X509.HBD.MultiMachine.json -DeleteLog -Force
If you wish to rebuild the cluster again. You need to delete the SF folder in C:\ProgramData
from all servers before the re-installation.
V. Sample Config Files
For your reference, the full set of configuration files and certificates had been uploaded onto here.
Take a look and build your own Service Fabric cluster.
Thanks for reading and Please share and like if the article is useful. Your comments and feedbacks are
valuable and helping me to have a better post.
Originally published at Drunk Coding.