PingFederate provides five dynamic discovery choices: AWS_PING, DNS_PING, S3_PING, NATIVE_S3_PING, and SWIFT_PING.
Note:

The S3_PING discovery method has been deprecated due to AWS deprecation of the SigV2 signing method. When deployed in AWS, the suggested discovery method is NATIVE_S3_PING. See the JGroups documentation for alternatives when deployed in other environments.

AWS_PING enables you to scale your PingFederate infrastructure using Amazon Elastic Compute Cloud (Amazon EC2) instances in the Amazon Web Service (AWS) cloud, in one or multiple regions. PingFederate queries AWS for a list of eligible EC2 instances. If PingFederate receives at least one node, a cluster exists, and it joins that cluster. If PingFederate receives no node, it forms a new cluster. Permissions to ec2:Describe* actions must either be enabled in the AWS Identity and Access Management (IAM) role assigned to the EC2 instance or be associated with the access_key parameter that you provide as part of the dynamic discovery configuration. Furthermore, you may also use a combination of tags and filters, in which case only EC2 instances that satisfy both criteria are returned.

S3_PING, SWIFT_PING, and NATIVE_S3_PING enable the flexibility to use both public and private cloud storage. PingFederate maintains cluster membership information in a centralized repository, a bucket in Amazon Simple Storage Service (Amazon S3) or a container in an OpenStack infrastructure. PingFederate contacts the repository for a list of nodes. If PingFederate receives at least one node, a cluster exists, and it joins the cluster and updates the repository with its information, including its IP address. If PingFederate receives no node, it forms a new cluster and updates the repository with its information so that the next node can find the new cluster. When PingFederate shuts down, it removes itself from the list and pushes an update to the repository.

NATIVE_S3_PING uses AWS SDK and provides a more stable connection by using built-in security features such as obtaining credentials through IAM server instance profiles. This protocol is the recommended dynamic discovery mechanism when you are running in AWS but not using Kubernetes.

DNS_PING uses DNS A or SRV records to perform discovery. This protocol is the recommended dynamic discovery mechanism when using Kubernetes. For more information, see http://www.jgroups.org/manual4/index.html#_dns_ping.

You can configure dynamic discovery in the <pf_install>/pingfederate/server/default/conf/tcp.xml file. You do not need to configure the pf.cluster.tcp.discovery.initial.hosts property in the run.properties file.

Important:

You must manually configure or synchronize the dynamic discovery properties in the tcp.xml file on each node. The tcp.xml file is not synchronized automatically across the nodes in a cluster, nor is it part of the Replicate Configuration process. Restart PingFederate servers if they are running.

  1. To configure cluster protocol properties, edit the <pf_install>/pingfederate/bin/run.properties file. Refer to the inline comments and the following table.
    Property Description
    pf.operational.mode Configure the operational mode of PingFederate. A a value of CLUSTERED_CONSOLE denotes a PingFederate administrative console node. CLUSTERED_ENGINE denotes a PingFederate runtime engine node.

    A PingFederate cluster has only one administrative console node. As you scale your PingFederate infrastructure, set the pf.operational.mode property value to CLUSTERED_ENGINE to deploy additional PingFederate runtime engine nodes.

    pf.cluster.tcp.discovery.initial.hosts Remove any configured value. No IP addresses are required here.
    pf.cluster.transport.protocol Set the value to tcp.
    pf.cluster.* Refer to the inline comments to configure the rest of the pf.cluster.* property values.
    Important:

    You must manually configure the clustering properties on each node. The run.properties file is not copied from the console node to the engine nodes automatically, nor is it part of the Replicate Configuration process. For more information, see Deploying cluster servers.

  2. Configure dynamic discovery properties.
    Edit the <pf_install>/pingfederate/server/default/conf/tcp.xml file. Refer to the inline comments and one of the following tables.
    AWS_PING
    Property Description
    port_number The port on which PingFederate listens for cluster communication.

    The default value is ${pf.cluster.bind.port}, which pulls the value defined by the pf.cluster.bind.port property in the <pf_install>/pingfederate/bin/run.properties file.

    port_range The number of additional ports that PingFederate can probe when attempting to connect to other nodes in the event that it fails to connect to the port specified by the port_number property.

    For example if the port_number property is 7600, a port_range property value of 0 means PingFederate will only try to connect at port 7600. If the port_range property value is set to 2, PingFederate will make up to two additional attempts, with the port value increasing by one each time. For example, if PingFederate fails to connect at port 7600, it will try at port 7601. If it fails again, it will try at port 7602.

    The default value is 0.

    regions A comma separated list of EC2 regions in which PingFederate will attempt discovery.

    If no regions are specified, only nodes in the same region as this node can be discovered. List all regions where you have nodes running.

    For information about regions, see the AWS documentation on Regions, Availability Zones, and Local Zones.

    tags A comma separated list of EC2 tag names.

    When specified, only EC2 instances that have been assigned with the specified tags can be discovered. If multiple tags are specified, only EC2 instances that have been assigned with all tags can be discovered.

    For information about tags, see the documentation from Amazon (docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html).

    filters A semi-colon separated list of key value pairs of system metadata.

    When specified, only EC2 instances that match the specified filters can be discovered. If multiple filters are specified, only EC2 instances that match all filters can be discovered.

    Note that you can enter a comma separated list of values for each filter. In this case, a filter is considered a match if one of the values is satisfied. For example, if you enter: filters="instance-type=t2.small,t2.medium;architecture=x86_64", then only EC2 instances that have an instance-type of either t2.small or t2.medium and also an architecture of x86_64 can be discovered.

    For information about filters, see the describe-instances documentation from Amazon.
    access_key and secret_key The access key and its secret key for the purpose of querying AWS for EC2 instances.

    Applicable and required only if permissions to ec2:Describe* actions are associated with the access key.

    Keys can be encrypted using the obfuscate utility (obfuscate.bat for Windows or obfuscate.sh for Linux), located in the <pf_install>/pingfederate/bin directory.

    log_aws_error_messages When set to true (the default), error messages received from AWS are logged to the server log.
    S3_PING
    Property Description
    location The name of the bucket in your Amazon S3 environment.

    For information about buckets, see the Create a bucket documentation from Amazon.
    access_key and secret_access_key The security credentials to access your Amazon S3 environment.

    For information about both keys, see the Understanding and getting your security credentials documentation from Amazon.

    Keys can be encrypted using the obfuscate utility (obfuscate.bat for Windows or obfuscate.sh for Linux), located in the <pf_install>/pingfederate/bin directory.

    remove_all_data_on_view_change When set to true (the default), JGroups cleans up data when it detects a view change.

    For more information, see jgroups.org/manual4/index.html#FILE_PING.

    write_data_on_find The default value is true, which resolves the issue where subclusters could fail to merge after a network partition.
    SWIFT_PING
    Property Description
    auth_type The authentication type.
    auth_url The authentication URL.
    username and password The security credentials.

    Password can be encrypted using the obfuscate utility (obfuscate.bat for Windows or obfuscate.sh for Linux), located in the <pf_install>/pingfederate/bin directory.

    tenant The name of your OpenStack Keystone tenant.
    container The name of the root container.

    For more information about each of the SWIFT_PING properties, see jgroups.org/manual4/index.html#_swift_ping.
    remove_all_data_on_view_change When set to true (the default), JGroups cleans up data when it detects a view change.

    For more information, see jgroups.org/manual4/index.html#FILE_PING.
    NATIVE_S3_PING
    Property Description
    region_name The name of the region in which discovery should be attempted.

    If no region is specified, only nodes in the same region as this node can be discovered.

    bucket_name The name of the bucket in your Amazon S3 environment.

    For information about buckets, see the Create a bucket documentation from Amazon.

    remove_all_data_on_view_change When set to true (the default), JGroups cleans up data when it detects a view change.

    For more information, see http://www.jgroups.org/manual4/index.html#FILE_PING.
    write_data_on_find Default value of true resolves the issue where subclusters could fail to merge after a network partition.
    DNS_PING
    Property Description
    dns_query A DNS query to the DNS Server and obtains information about the cluster members. For example, jgroups-dns-ping.myproject.svc.cluster.local.

    For more information, see http://www.jgroups.org/manual4/index.html#_dns_ping.

  3. Start or restart PingFederate.
  4. Repeat these steps for each node.
    Note: You must repeat these steps for new nodes when they are added.

After the initial setup, your nodes are ready to be deployed, undeployed, and redeployed as traffic volume changes.

Discovery mechanisms are separate from runtime state-management architectures. Discovery mechanisms determine how to find nodes to retrieve cluster information for the purpose of joining and rejoining a cluster. Runtime state-management architectures determine which nodes session-state information is shared to and fetched from.

PingFederate supports adaptive clustering and directed clustering runtime state-management architectures. When opting for dynamic discovery, consider enabling adaptive clustering whenever possible. If multiple regions are involved, configure multi-region support for adaptive clustering as well. For more information and configuration steps, see Adaptive clustering.

Regardless of the chosen runtime state-management architecture, all nodes must still be able to communicate with other nodes for clustering-protocol messages. For more information, see Runtime state-management architectures.