Connect-ServiceFabricCluster

Creates a connection to a Service Fabric cluster.

Syntax

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>]
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>]
Connect-ServiceFabricCluster
       [-ConnectionEndpoint] <String[]>
       [-AllowNetworkConnectionOnly]
       [-X509Credential]
       [-ServerCommonName <String[]>]
       [-ServerCertThumbprint <String[]>]
       -FindType <X509FindType>
       -FindValue <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>]
Connect-ServiceFabricCluster
       [-ConnectionEndpoint] <String[]>
       [-AllowNetworkConnectionOnly]
       [-ServerCommonName <String[]>]
       [-ServerCertThumbprint <String[]>]
       [-DSTS]
       -MetaDataEndpoint <String>
       [-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>]
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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AuthTokenBufferSize

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

Type:Int64
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AzureActiveDirectory

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

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-CloudServiceDNSNames

This parameter is for internal use only.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CloudServiceName

This parameter is for internal use only.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ClusterSpn

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

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ConnectionInitializationTimeoutInSec

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

Type:Double
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DSTS

This parameter is for internal use only.

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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
Type:X509FindType
Accepted values:FindByThumbprint, FindBySubjectName, FindBySubjectDistinguishedName, FindByIssuerName, FindByIssuerDistinguishedName, FindBySerialNumber, FindByTimeValid, FindByTimeNotYetValid, FindByTimeExpired, FindByTemplateName, FindByApplicationPolicy, FindByCertificatePolicy, FindByExtension, FindByKeyUsage, FindBySubjectKeyIdentifier
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-FindValue

Specifies filter value to search a certificate in certificate store.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-GetMetadata

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Double
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Double
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Double
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Interactive

Indicates whether the cmdlet operates interactively.

Type:Boolean
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Double
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MetaDataEndpoint

This parameter is for internal use only.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-PartitionLocationCacheLimit

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

Type:Int64
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SecurityToken

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

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Double
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipChecks

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

Type:Boolean
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StoreLocation

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

  • CurrentUser
  • LocalMachine
Type:StoreLocation
Accepted values:CurrentUser, LocalMachine
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StoreName

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

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TimeoutSec

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

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WindowsCredential

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

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-X509Credential

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

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Inputs

None

Outputs

System.Object