k8s.io/kubernetes@v1.31.0-alpha.0.0.20240520171757-56147500dadc/pkg/kubelet/pluginmanager/pluginwatcher/README.md (about)

     1  # Plugin Registration Service
     2  
     3  This folder contains a utility, pluginwatcher, for Kubelet to register
     4  different types of node-level plugins such as device plugins or CSI plugins.
     5  It discovers plugins by monitoring inotify events under the directory returned by
     6  kubelet.getPluginsDir(). We will refer to this directory as PluginsDir.
     7  
     8  Plugins are expected to implement the gRPC registration service specified in
     9  pkg/kubelet/apis/pluginregistration/v*/api.proto.
    10  
    11  ## Plugin Discovery
    12  
    13  The pluginwatcher service will discover plugins in the PluginDir when they
    14  place a socket in that directory or, at Kubelet start if the socket is already
    15  there.
    16  
    17  This socket filename should not start with a '.' as it will be ignored.
    18  
    19  
    20  ## gRPC Service Lifecycle
    21  
    22  For any discovered plugin, kubelet will issue a Registration.GetInfo gRPC call
    23  to get plugin type, name, endpoint and supported service API versions.
    24  
    25  If any of the following steps in registration fails, on retry registration will
    26  start from scratch:
    27  - Registration.GetInfo is called against socket.
    28  - Validate is called against internal plugin type handler.
    29  - Register is called against internal plugin type handler.
    30  - NotifyRegistrationStatus is called against socket to indicate registration result.
    31  
    32  During plugin initialization phase, Kubelet will issue Plugin specific calls
    33  (e.g: DevicePlugin::GetDevicePluginOptions).
    34  
    35  Once Kubelet determines that it is ready to use your plugin it will issue a
    36  Registration.NotifyRegistrationStatus gRPC call.
    37  
    38  If the plugin removes its socket from the PluginDir this will be interpreted
    39  as a plugin Deregistration. If any of the following steps in deregistration fails,
    40  on retry deregistration will start from scratch:
    41  - Registration.GetInfo is called against socket.
    42  - DeRegisterPlugin is called against internal plugin type handler.
    43  
    44  
    45  ## gRPC Service Overview
    46  
    47  Here are the general rules that Kubelet plugin developers should follow:
    48  - Run plugin as 'root' user. Currently creating socket under PluginsDir, a root owned
    49    directory, requires plugin process to be running as 'root'.
    50  
    51  - The plugin name sent during Registration.GetInfo grpc should be unique
    52    for the given plugin type (CSIPlugin or DevicePlugin).
    53  
    54  - The socket path needs to be unique within one directory, in normal case,
    55    each plugin type has its own sub directory, but the design does support socket file
    56    under any sub directory of PluginSockDir.
    57  
    58  - A plugin should clean up its own socket upon exiting or when a new instance
    59    comes up. A plugin should NOT remove any sockets belonging to other plugins.
    60  
    61  - A plugin should make sure it has service ready for any supported service API
    62    version listed in the PluginInfo.
    63  
    64  - For an example plugin implementation, take a look at example_plugin.go
    65    included in this directory.
    66  
    67  
    68  # Kubelet Interface
    69  
    70  For any kubelet components using the pluginwatcher module, you will need to
    71  implement the PluginHandler interface defined in the types.go file.
    72  
    73  The interface is documented and the implementations are registered with the
    74  pluginwatcher module in kubelet.go by calling AddHandler(pluginType, handler).
    75  
    76  
    77  The lifecycle follows a simple state machine:
    78  
    79                 Validate -> Register -> DeRegister
    80                    ^          +
    81                    |          |
    82                    +--------- +
    83  
    84  The pluginwatcher calls the functions with the received plugin name, supported
    85  service API versions and the endpoint to call the plugin on.
    86  
    87  The Kubelet component that receives this callback can acknowledge or reject
    88  the plugin according to its own logic, and use the socket path to establish
    89  its service communication with any API version supported by the plugin.