Share via

Connect-ServiceFabricCluster

Module:
ServiceFabric Module

Creates a connection to a Service Fabric cluster.

Syntax

Default 

Connect-ServiceFabricCluster
    [[-ConnectionEndpoint] <String[]>]
    [-AllowNetworkConnectionOnly]
    [-ConnectionInitializationTimeoutInSec <Double>]
    [-HealthOperationTimeoutInSec <Double>]
    [-HealthReportSendIntervalInSec <Double>]
    [-HealthReportRetrySendIntervalInSec <Double>]
    [-KeepAliveIntervalInSec <Double>]
    [-ServiceChangePollIntervalInSec <Double>]
    [-PartitionLocationCacheLimit <Int64>]
    [-AuthTokenBufferSize <Int64>]
    [-SkipChecks <Boolean>]
    [-TimeoutSec <Int32>]
    [<CommonParameters>]

Windows 

Connect-ServiceFabricCluster
    [-ConnectionEndpoint] <String[]>
    [-AllowNetworkConnectionOnly]
    [-WindowsCredential]
    [-ClusterSpn <String>]
    [-ConnectionInitializationTimeoutInSec <Double>]
    [-HealthOperationTimeoutInSec <Double>]
    [-HealthReportSendIntervalInSec <Double>]
    [-HealthReportRetrySendIntervalInSec <Double>]
    [-KeepAliveIntervalInSec <Double>]
    [-ServiceChangePollIntervalInSec <Double>]
    [-PartitionLocationCacheLimit <Int64>]
    [-AuthTokenBufferSize <Int64>]
    [-SkipChecks <Boolean>]
    [-TimeoutSec <Int32>]
    [<CommonParameters>]

X509 

Connect-ServiceFabricCluster
    [-ConnectionEndpoint] <String[]>
    -FindType <X509FindType>
    -FindValue <String>
    [-AllowNetworkConnectionOnly]
    [-X509Credential]
    [-ServerCommonName <String[]>]
    [-ServerCertThumbprint <String[]>]
    [-StoreLocation <StoreLocation>]
    [-StoreName <String>]
    [-ConnectionInitializationTimeoutInSec <Double>]
    [-HealthOperationTimeoutInSec <Double>]
    [-HealthReportSendIntervalInSec <Double>]
    [-HealthReportRetrySendIntervalInSec <Double>]
    [-KeepAliveIntervalInSec <Double>]
    [-ServiceChangePollIntervalInSec <Double>]
    [-PartitionLocationCacheLimit <Int64>]
    [-AuthTokenBufferSize <Int64>]
    [-SkipChecks <Boolean>]
    [-TimeoutSec <Int32>]
    [<CommonParameters>]

Dsts 

Connect-ServiceFabricCluster
    [-ConnectionEndpoint] <String[]>
    -MetaDataEndpoint <String>
    [-AllowNetworkConnectionOnly]
    [-ServerCommonName <String[]>]
    [-ServerCertThumbprint <String[]>]
    [-DSTS]
    [-CloudServiceName <String>]
    [-CloudServiceDNSNames <String[]>]
    [-ConnectionInitializationTimeoutInSec <Double>]
    [-HealthOperationTimeoutInSec <Double>]
    [-HealthReportSendIntervalInSec <Double>]
    [-HealthReportRetrySendIntervalInSec <Double>]
    [-KeepAliveIntervalInSec <Double>]
    [-ServiceChangePollIntervalInSec <Double>]
    [-PartitionLocationCacheLimit <Int64>]
    [-AuthTokenBufferSize <Int64>]
    [-Interactive <Boolean>]
    [-SkipChecks <Boolean>]
    [-TimeoutSec <Int32>]
    [<CommonParameters>]

Aad 

Connect-ServiceFabricCluster
    [-ConnectionEndpoint] <String[]>
    [-AllowNetworkConnectionOnly]
    [-ServerCommonName <String[]>]
    [-ServerCertThumbprint <String[]>]
    [-AzureActiveDirectory]
    [-SecurityToken <String>]
    [-GetMetadata]
    [-ConnectionInitializationTimeoutInSec <Double>]
    [-HealthOperationTimeoutInSec <Double>]
    [-HealthReportSendIntervalInSec <Double>]
    [-HealthReportRetrySendIntervalInSec <Double>]
    [-KeepAliveIntervalInSec <Double>]
    [-ServiceChangePollIntervalInSec <Double>]
    [-PartitionLocationCacheLimit <Int64>]
    [-AuthTokenBufferSize <Int64>]
    [-SkipChecks <Boolean>]
    [-TimeoutSec <Int32>]
    [<CommonParameters>]

Description

The Connect-ServiceFabricCluster cmdlet creates a connection to a standalone Service Fabric cluster that allows you to run management actions for that cluster. After you connect to a cluster, you can view the settings of the connection by using the Get-ServiceFabricClusterConnection cmdlet.

To manage Service Fabric clusters, start Windows PowerShell by using the Run as administrator option.

Examples

Example 1: Connect to a cluster

PS C:\> Connect-ServiceFabricCluster -ConnectionEndpoint "ServiceFabric01.ContosoCloudApp.net:19000"

This command creates a connection to the specified cluster.

Example 2: Connect to a cluster using an X.509 certificate

PS C:\> $ConnectArgs = @{
    ConnectionEndpoint = 'mycluster.cloudapp.net:19000'
    X509Credential = $True
    StoreLocation = 'CurrentUser'
    StoreName = "MY"
    ServerCommonName = "mycluster.cloudapp.net"
    FindType = 'FindByThumbprint'
    FindValue = "AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00"
}
PS C:\> Connect-ServiceFabricCluster @ConnectArgs

This command connects to a cluster using an X.509 certificate. This command uses the splatting feature of Windows PowerShell to create a hash table for parameters, and then supplies them to the Connect-ServiceFabricCluster cmdlet.

Example 3: Connect to a managed cluster using an X.509 certificate

PS C:\> $resourceGroup = 'mycluster'
PS C:\> $managedCluster = Get-AzServiceFabricManagedCluster -ResourceGroupName $resourceGroup
PS C:\> $ConnectArgs = @{
    ConnectionEndpoint = "$($managedCluster.Fqdn):$($managedCluster.ClientConnectionPort)"
    X509Credential = $true
    StoreLocation = 'CurrentUser'
    StoreName = "MY"
    ServerCertThumbprint = (Get-AzResource -ResourceId $managedCluster.Id).Properties.clusterCertificateThumbprints
    FindType = 'FindByThumbprint'
    FindValue = "AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00"
}
PS C:\> Connect-ServiceFabricCluster @ConnectArgs

Note: Connecting to a managed cluster requires PowerShell 'Az.ServiceFabric' and 'Az.Resources' modules to query for server certificate thumbprints.

This command first queries managed cluster resource for current server certificate thumbprints, then connects to cluster using X509 certificate. Provide name of resource group for managed cluster to retrieve connection information including the full resource id for the managed cluster. See Connect to a Service Fabric managed cluster.

This command then connects to a cluster using an X.509 certificate.

Example 4: Connect to a cluster using Azure Active Directory

PS C:\> $ConnectArgs = @{
    ConnectionEndpoint = 'mycluster.cloudapp.net:19000'
    AzureActiveDirectory = $True
    ServerCertThumbprint = "AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00"
}
PS C:\> Connect-ServiceFabricCluster @ConnectArgs

This command connects to a cluster using Azure Active Directory (AAD) authentication. This command uses the splatting feature of Windows PowerShell to create a hash table for parameters, and then supplies them to the Connect-ServiceFabricCluster cmdlet.

Example 5: Connect to a cluster secured with a group-managed service account

PS C:\> $ConnectArgs = @{
    ConnectionEndpoint = 'mycluster.cloudapp.net:19000'
    WindowsCredential = $True
    ClusterSpn = 'ServiceFabric/MyCluster.MyDomain.MyOrg'
}
PS C:\> Connect-ServiceFabricCluster @connectArgs

This command uses the splatting feature of Windows PowerShell to create a hash table for parameters, and then supplies them to the Connect-ServiceFabricCluster cmdlet.

Example 6: Connect to a cluster secured with machine accounts

PS C:\> $connectArgs = @{
    ConnectionEndpoint = 'mycluster.cloudapp.net:19000'
    WindowsCredential = $True
}
PS C:\> Connect-ServiceFabricCluster @connectArgs

This command connects to a cluster secured with machine accounts.

Example 7: Connect to a cluster without the primary checks

PS C:\> Connect-ServiceFabricCluster -ConnectionEndpoint -SkipChecks $True "ServiceFabric01.ContosoCloudApp.net:19000"

This command creates a connection to the specified cluster.

Parameters

-AllowNetworkConnectionOnly

Indicates that the cmdlet allows connecting to the cluster even when system services are unresponsive as long as an underlying network connection can be established.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-AuthTokenBufferSize

When connecting with AzureActiveDirectory, specifies the buffer size to allocate for security token acquisition.

Parameter properties

Type:Int64
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-AzureActiveDirectory

Specifies that Azure Active Directory should be used for authentication and authorization.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Aad
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-CloudServiceDNSNames

This parameter is for internal use only.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Dsts
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-CloudServiceName

This parameter is for internal use only.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Dsts
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ClusterSpn

Specifies the cluster security principal name to use for Windows credential.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Windows
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ConnectionEndpoint

Specifies an array of connection endpoints for the cluster in the format ClusterAddress: ClientConnectionEndpoint, where ClusterAddress is the IPv4 address, IPv6 address, or fully qualified domain name (FQDN) of the cluster node to connect to and ClientConnectionEndpoint is the client connection port specified in the cluster manifest. Enclose IPv6 addresses in square brackets ([]). Valid endpoints have the following form:

IPv4Address:ClientConnectionEndpoint [IPv6Address]:ClientConnectionEndpoint FQDN:ClientConnectionEndpoint

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Default
Position:0
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ConnectionInitializationTimeoutInSec

Specifies the time-out period, in seconds, for the operation.

Parameter properties

Type:Double
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-DSTS

This parameter is for internal use only.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Dsts
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-FindType

Specifies the type of FindValue for searching certificate in certificate store. The following filter types are supported:

  • FindByThumbprint. Find certificate by certificate thumbprint.
  • FindBySubjectName. Search certificate in certificate store by subject distinguished name or common name, when subject distinguished name is provided in FindValue, subject name in the certificate must be encoded in ASN encoding due to a restriction in native Windows crypto API. There is no such restriction when common name is provided in FindValue.
  • FindBySubjectDistinguishedName
  • FindByIssuerName
  • FindByIssuerDistinguishedName
  • FindBySerialNumber
  • FindByTimeValid
  • FindByTimeNotYetValid
  • FindByTimeExpired
  • FindByTemplateName
  • FindByApplicationPolicy
  • FindByCertificatePolicy
  • FindByExtension
  • FindByKeyUsage
  • FindBySubjectKeyIdentifier

Parameter properties

Type:X509FindType
Default value:None
Accepted values:FindByThumbprint, FindBySubjectName, FindBySubjectDistinguishedName, FindByIssuerName, FindByIssuerDistinguishedName, FindBySerialNumber, FindByTimeValid, FindByTimeNotYetValid, FindByTimeExpired, FindByTemplateName, FindByApplicationPolicy, FindByCertificatePolicy, FindByExtension, FindByKeyUsage, FindBySubjectKeyIdentifier
Supports wildcards:False
DontShow:False

Parameter sets

X509
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-FindValue

Specifies filter value to search a certificate in certificate store.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

X509
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-GetMetadata

When connecting with AzureActiveDirectory, anonymously retrieves the metadata used for token acquisition and does not attempt any authentication.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Aad
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HealthOperationTimeoutInSec

Specifies the time-out period, in seconds, for sending health reports. When a health operation times out or fails with a communication error, the health client internally retries the operation.

Parameter properties

Type:Double
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HealthReportRetrySendIntervalInSec

Specifies the interval, in seconds, at which the health client retries sending the reports that failed to be sent or to be persisted in health store. The minimum supported value is 1 second.

Parameter properties

Type:Double
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HealthReportSendIntervalInSec

Specifies the interval, in seconds, at which the health client sends the health reports to health store. If set to 0, the health client will send the reports immediately.

Parameter properties

Type:Double
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Interactive

Indicates whether the cmdlet operates interactively.

Parameter properties

Type:Boolean
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Dsts
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-KeepAliveIntervalInSec

Specifies the connection keep-alive period in seconds. This interval prevents a connection from being terminated because of inactivity during operations that run asynchronously.

Parameter properties

Type:Double
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-MetaDataEndpoint

This parameter is for internal use only.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Dsts
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-PartitionLocationCacheLimit

Specifies the number of partitions cached for service resolution. The default value is 0, which signifies no limit.

Parameter properties

Type:Int64
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-SecurityToken

When connecting with AzureActiveDirectory, the specified security token is used directly for authentication and authorization rather than performing interactive user login.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Aad
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ServerCertThumbprint

Specifies an array of the expected thumbprints for the cluster side. These thumbprints are used to authenticate that the cmdlet connects to the endpoint of the correct cluster during x509 or Azure Active Directory mutual authentication.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

X509
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
Dsts
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
Aad
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ServerCommonName

Specifies an array of the expected common names for the cluster side. These names are used to authenticate that the cmdlet connects to the endpoint of the correct cluster during x509 or Azure Active Directory mutual authentication.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

X509
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
Dsts
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
Aad
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ServiceChangePollIntervalInSec

Specifies the interval, in seconds, at which the fabric client polls for service changes. This interval is used by old model of poll-based service address change notifications.

Parameter properties

Type:Double
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-SkipChecks

Indicates to bypass system service responsiveness validation checks when connecting to the cluster.

Parameter properties

Type:Boolean
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-StoreLocation

Specifies the store location of a certificate. The acceptable values for this parameter are:

  • CurrentUser
  • LocalMachine

Parameter properties

Type:StoreLocation
Default value:None
Accepted values:CurrentUser, LocalMachine
Supports wildcards:False
DontShow:False

Parameter sets

X509
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-StoreName

Specifies the name of the certificate store to load the client certificate.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

X509
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TimeoutSec

Specifies the time-out period, in seconds, for the operation.

Parameter properties

Type:Int32
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-WindowsCredential

Indicates that the cmdlet uses Windows credentials to connect to a Service Fabric cluster.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

Windows
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-X509Credential

Indicates that the cmdlet uses an x509 certificate to perform mutual authentication with a Service Fabric cluster.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

X509
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

None

Outputs

System.Object