--- title: Deploy PingDirectoryProxy and PingDirectory with automatic backend discovery description: Since version 8.3 of PingDirectoryProxy, proxy servers can use automatic server discovery to determine the backend PingDirectory servers, rather than adding those servers individually to the configuration. This page describes how to use this feature with the PingDirectory and PingDirectoryProxy Docker images and the ping-devops Helm chart. component: devops page_id: devops::deployment/deployPDProxyBackendDiscovery canonical_url: https://developer.pingidentity.com/devops/deployment/deployPDProxyBackendDiscovery.html section_ids: devops-configuring-the-proxy-instance-to-join-the-directory-topology: Configuring the proxy instance to join the directory topology devops-waiting-for-the-directory-topology-to-be-ready-before-starting: Waiting for the directory topology to be ready before starting devops-configuring-automatic-server-discovery-on-proxy-using-a-server-profile: Configuring automatic server discovery on proxy using a server profile devops-setting-load-balancing-algorithm-names-on-the-directory-instances: Setting load balancing algorithm names on the directory instances devops-removing-the-proxy-server-from-the-topology-on-pod-shutdown: Removing the proxy server from the topology on pod shutdown devops-automatic-server-discovery-when-directory-and-proxy-pods-are-split-across-multiple-clusters: Automatic server discovery when directory and proxy pods are split across multiple clusters --- # Deploy PingDirectoryProxy and PingDirectory with automatic backend discovery Since version 8.3 of PingDirectoryProxy, proxy servers can use [automatic server discovery](https://docs.pingidentity.com/pingdirectory/11.0/pingdirectoryproxy_server_administration_guide/pd_proxy_auto_backend_server_discovery.html) to determine the backend PingDirectory servers, rather than adding those servers individually to the configuration. This page describes how to use this feature with the PingDirectory and PingDirectoryProxy Docker images and the ping-devops Helm chart. The directory and proxy Docker images added support for this feature as of the 2310 release, and the ping-devops Helm chart added support in release `0.9.20`. ## Configuring the proxy instance to join the directory topology The first step of enabling automatic server discovery is to have the proxy server(s) join the topology of replicating directory servers. To enable this, the proxy Docker image supports the following variables: * `JOIN_PD_TOPOLOGY`: Set to `true` to add the proxy instance to a directory topology * `PINGDIRECTORY_HOSTNAME`: The hostname of the directory server to connect with when joining the topology * `PINGDIRECTORY_LDAPS_PORT`: The LDAPS port of the directory server to connect with when joining the topology If all three of these variables are set, the proxy server will join the designated topology after the server starts up. ### Waiting for the directory topology to be ready before starting The designated directory server must be running for the proxy server to join the topology. To ensure directory is running before proxy attempts to join, a `wait-for` can be used. For example, using the ping-devops Helm chart, the following values yaml instructs proxy to wait until the second `pingdirectory` pod is running before starting and attempting to join the topology. "releasename" can be replaced with the Helm release name. ``` initContainers: wait-for-pd: name: wait-for-pd image: pingidentity/pingtoolkit:2309 command: ['sh', '-c', 'echo "Waiting for PingDirectory..." && wait-for releasename-pingdirectory-1.releasename-pingdirectory-cluster:1636 -t 300 -- echo "PingDirectory running"'] pingdirectory: container: replicaCount: 2 enabled: true envs: SERVER_PROFILE_URL: https://github.com/pingidentity/pingidentity-server-profiles.git SERVER_PROFILE_PATH: baseline/pingdirectory LOAD_BALANCING_ALGORITHM_NAMES:dc_example_dc_com-fewest-operations;dc_example_dc_com-failover pingdirectoryproxy: includeInitContainers: - wait-for-pd container: replicaCount: 1 enabled: true envs: SERVER_PROFILE_URL: https://github.com/pingidentity/pingidentity-server-profiles.git SERVER_PROFILE_PATH: pingdirectoryproxy-automatic-server-discovery/pingdirectoryproxy JOIN_PD_TOPOLOGY: "true" PINGDIRECTORY_HOSTNAME: releasename-pingdirectory-0.releasename-pingdirectory-cluster PINGDIRECTORY_LDAPS_PORT: "1636" ``` ## Configuring automatic server discovery on proxy using a server profile The proxy server must also be configured via `dsconfig` to enable automatic server discovery. For an example, see the automatic server discovery [server profile](https://github.com/pingidentity/pingidentity-server-profiles/tree/master/pingdirectoryproxy-automatic-server-discovery). Use the `pingdirectoryproxy-automatic-server-discovery/pingdirectoryproxy` profile path. The profile contains the static automatic-discovery `dsconfig` plus a startup hook for multi-region deployments. When `JOIN_PD_TOPOLOGY=true` and both `K8S_CLUSTERS` and `K8S_CLUSTER` are set, the startup hook: * Treats `K8S_CLUSTER` as the local proxy location * Ensures each configured failover location exists as a peer location * Sets the local location's `preferred-failover-location` values in the same order as the non-local cluster names in `K8S_CLUSTERS` * Uses `PREFERRED_FAILOVER_LOCATIONS`, when set, as an explicit ordered subset of non-local clusters from `K8S_CLUSTERS` * Re-applies that configuration on restart ## Setting load balancing algorithm names on the directory instances To associate directory servers with the load balancing algorithms configured on the proxy server, the `load-balancing-algorithm-name` property must be set. This can be done with the `LOAD_BALANCING_ALGORITHM_NAMES` environment variable in the directory Docker image. When using multiple algorithm names, separate them with a `;`. See the above yaml snippet for an example. ## Removing the proxy server from the topology on pod shutdown By default the proxy server will rejoin the topology automatically on restarts. In the `ping-devops` Helm chart, proxy does not use a persistent volume, so it will fully restart and rejoin the topology during each startup. Another option, which allows for scaling down the number of proxy servers, is adding a `preStop` hook to remove the proxy server from the topology. In general this can cause slowness because it will run whenever a pod stops, but it ensures that scaling down the number of proxies does not leave outdated servers in the topology registry. For example: ``` pingdirectoryproxy: container: # Add the preStop hook to run the remove-defunct-server tool lifecycle: preStop: exec: command: - /opt/staging/hooks/90-shutdown-sequence.sh ``` ## Automatic server discovery when directory and proxy pods are split across multiple clusters When [deploying directory pods across multiple Kubernetes clusters](deployPDMultiRegion.html), some additional configuration needs to be added to allow proxy to join the directory topology and enable automatic server discovery. Essentially, the proxy workload will need to have similar variables and network access as the directory workload (see the directory multi-cluster doc linked above). In addition, proxy will need the right variables set to join the topology and the right wait-for logic to wait for the other servers to be ready before starting and joining the topology. For location-aware load balancing algorithms, joining the topology is not sufficient by itself. The proxy must also have peer `Location` objects and `preferred-failover-location` values configured for its local location. The automatic-discovery profile now derives that configuration from `K8S_CLUSTERS`, `K8S_CLUSTER`, and optionally `PREFERRED_FAILOVER_LOCATIONS` during startup. For example, if `K8S_CLUSTERS="west east north"` and `K8S_CLUSTER="west"`, then the proxy creates peer locations for `east` and `north` and sets the local `west` location to prefer `east` first and `north` second. To override that default order or use only a subset, set `PREFERRED_FAILOVER_LOCATIONS` to the ordered non-local locations to apply. See [here](https://github.com/pingidentity/pingidentity-devops-getting-started/tree/master/30-helm/multi-region/pingdirectoryproxy-automatic-server-discovery) for a complete Helm example.