Dynamic discovery is well suited for environments where traffic volume may spike and require additional resources during the peak period to handle the increased traffic. This elastic scaling capability helps you to bring additional PingFederate engine nodes online with no additional configuration changes after the initial setup. PingFederate provides five dynamic discovery choices: AWS_PING, S3_PING, SWIFT_PING, NATIVE_S3_PING, and DNS_PING.

With AWS_PING, you 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. It is worth noting that 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 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.

With S3_PING, SWIFT_PING, and NATIVE_S3_PING, you have 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 reach out and 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 about DNS_PING, see http://www.jgroups.org/manual4/index.html#_dns_ping.

Dynamic discovery configuration is maintained in the tcp.xml file, located in the <pf_install>/pingfederate/server/default/conf directory. No effort is required to maintain 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; it is also not part of the Replicate Configuration process. PingFederate servers must be restarted if running.

  1. Configure cluster protocol properties.
    Edit the run.properties file, located in the <pf_install>/pingfederate/bin directory. 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 while a value of CLUSTERED_ENGINE denotes a PingFederate runtime engine node.

    In a PingFederate cluster, there is 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; it is also not part of the Replicate Configuration process. If you require more information, see Deploying cluster servers.

  2. Configure dynamic discovery properties.
    Edit the tcp.xml file, located in the <pf_install>/pingfederate/server/default/conf directory. 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 may probe when attempting to connect to other nodes in the event that it fails to do so at the port specified by the port_number property.

    Suppose the port number is 7600, as determined by the port_number property, a port_range property value of 0 means PingFederate will only try to connect at port 7600; it will not try at a different port if it fails to connect at 7600. If the port_range property value is set to 2, PingFederate can try up to two additional attempts; the port value increases 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 discovery should be attempted.

    If no regions are specified, only nodes in the same region as this node can be discovered. If nodes are running in multiple regions, it is recommended to list all regions in this property.

    For information about regions, see the documentation from Amazon (docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).

    tags A comma separated list of EC2 tag names.

    When specified, only EC2 instances that have been assigned with the specified tag (or 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 filter (or 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 so long as 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 documentation from Amazon (docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html).

    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 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 documentation from Amazon (docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).

    access_key and secret_access_key The security credentials to access your Amazon S3 environment.

    For information about both keys, see the documentation from Amazon (docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).

    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 http://www.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 http://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 http://www.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 documentation from Amazon (docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).

    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 The default value is true, which resolves the issue where subclusters could fail to merge after a network partition.
    DNS_PING
    Property Description
    dns_query A DNS query that queries 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 on the rest of the nodes (and any new nodes, as needed).

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

It is worth mentioning that discovery mechanisms are separated from runtime state-management architectures. Discovery mechanisms determine how to find nodes to retrieve cluster information for the purpose of joining and rejoining such cluster. Runtime state-management architectures determine to and from which nodes session-state information is shared and fetched.

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.

Note:

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