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.