k8s.io/kubernetes@v1.29.3/test/images/pets/peer-finder/README.md (about) 1 # Peer finder 2 3 This is a simple peer finder daemon that is useful with StatefulSet and related use cases. 4 5 All it does is watch DNS for changes in the set of endpoints that are part of the governing service 6 of the PetSet. It periodically looks up the SRV record of the DNS entry that corresponds to a Kubernetes 7 Service which enumerates the set of peers for this the specified service. 8 9 Be sure to use the `service.alpha.kubernetes.io/tolerate-unready-endpoints` on the governing service 10 of the StatefulSet so that all peers are listed in endpoints before any peers are started. 11 12 There are several ways to bundle it with your main application. 13 14 1. In an [init container](http://kubernetes.io/docs/user-guide/pods/init-container/), 15 to help your pod determine its peers when it first started (determine the desired set of 16 peers from the governing service of the StatefulSet. For this use case, the `--on-start` option 17 can be used, but the `--on-change` option should not be used since the init container will no 18 longer be running after the pod is started. An example of an `--on-start` script would be to 19 edit a configuration file for the main app to insert the list of peers. This file needs to be 20 on a Volume shared between the init container and the main container. 21 2. In a sidecar (e.g. a second container in the same pod as the main app), in which case the `--on-change` 22 option can be used, but `--on-start` may not be useful without a way to guarantee the ordering 23 of the sidecar relative to the main app container. An example of an on-change script would be to 24 send an administrative command to the main container over the localhost network. (Note that signalling 25 is not practical since pods currently do not share a PID namespace). 26 3. As pid 1 of the main container, in which case both `--on-change` and `--on-start` may be used. 27 In this mode, the ordering of the peer-finder relative to the main app is ensured by having the peer 28 finder start the main app. An example script would be to modify a configuration file and send SIGHUP 29 to the main process. 30 4. Both 1 and 2. 31 32 Options 1 and 2 and 4 may be preferable since they do not require changes to the main container image. 33 Option 3 is useful is signalling is necessary. 34 35 The peer-finder tool is intended to help legacy applications run in containers on Kubernetes. 36 If possible, it may be preferable to modify an application to poll its own DNS to determine its peer set. 37 38 Not all StatefulSets are able to be scaled. For unscalable StatefulSets, only the on-start message is needed, and 39 so option 1 is a good choice. 40 41 ## DNS Considerations 42 Unless specified by the `-domain` argument, `peer-finder` will determine the FQDN of the pod by examining the 43 `/etc/resolv.conf` file, looking for a `search` line and looking for the best match. 44 45 If your pod is not using the default `dnsPolicy` value which is `ClusterFirst` as the DNS policy, you may need 46 to provide the `-domain` argument. In most common configurations, `-domain=cluster.local` will be the correct setting.