cache

Documentation

Overview

Package cache implements data structures used by the kubelet plugin manager to keep track of registered plugins.

Package cache implements data structures used by the kubelet plugin manager to keep track of registered plugins.

Index

• type ActualStateOfWorld
  • func NewActualStateOfWorld() ActualStateOfWorld
• type DesiredStateOfWorld
  • func NewDesiredStateOfWorld() DesiredStateOfWorld
• type PluginHandler
• type PluginInfo
  • func (plugin *PluginInfo) GenerateError(prefixMsg string, err error) (simpleErr, detailedErr error)
  • func (plugin *PluginInfo) GenerateErrorDetailed(prefixMsg string, err error) (detailedErr error)
  • func (plugin *PluginInfo) GenerateMsg(prefixMsg, suffixMsg string) (simpleMsg, detailedMsg string)
  • func (plugin *PluginInfo) GenerateMsgDetailed(prefixMsg, suffixMsg string) (detailedMsg string)

Types

type ActualStateOfWorld

type ActualStateOfWorld interface {

	// GetRegisteredPlugins generates and returns a list of plugins
	// that are successfully registered plugins in the current actual state of world.
	GetRegisteredPlugins() []PluginInfo

	// AddPlugin add the given plugin in the cache.
	// An error will be returned if socketPath of the PluginInfo object is empty.
	// Note that this is different from desired world cache's AddOrUpdatePlugin
	// because for the actual state of world cache, there won't be a scenario where
	// we need to update an existing plugin if the timestamps don't match. This is
	// because the plugin should have been unregistered in the reconciler and therefore
	// removed from the actual state of world cache first before adding it back into
	// the actual state of world cache again with the new timestamp
	AddPlugin(pluginInfo PluginInfo) error

	// RemovePlugin deletes the plugin with the given socket path from the actual
	// state of world.
	// If a plugin does not exist with the given socket path, this is a no-op.
	RemovePlugin(socketPath string)

	// PluginExists checks if the given plugin exists in the current actual
	// state of world cache with the correct timestamp
	PluginExistsWithCorrectTimestamp(pluginInfo PluginInfo) bool
}

ActualStateOfWorld defines a set of thread-safe operations for the kubelet plugin manager's actual state of the world cache. This cache contains a map of socket file path to plugin information of all plugins attached to this node.

func NewActualStateOfWorld

func NewActualStateOfWorld() ActualStateOfWorld

NewActualStateOfWorld returns a new instance of ActualStateOfWorld

type DesiredStateOfWorld

type DesiredStateOfWorld interface {
	// AddOrUpdatePlugin add the given plugin in the cache if it doesn't already exist.
	// If it does exist in the cache, then the timestamp of the PluginInfo object in the cache will be updated.
	// An error will be returned if socketPath is empty.
	AddOrUpdatePlugin(socketPath string) error

	// RemovePlugin deletes the plugin with the given socket path from the desired
	// state of world.
	// If a plugin does not exist with the given socket path, this is a no-op.
	RemovePlugin(socketPath string)

	// GetPluginsToRegister generates and returns a list of plugins
	// in the current desired state of world.
	GetPluginsToRegister() []PluginInfo

	// PluginExists checks if the given socket path exists in the current desired
	// state of world cache
	PluginExists(socketPath string) bool
}

DesiredStateOfWorld defines a set of thread-safe operations for the kubelet plugin manager's desired state of the world cache. This cache contains a map of socket file path to plugin information of all plugins attached to this node.

func NewDesiredStateOfWorld

func NewDesiredStateOfWorld() DesiredStateOfWorld

NewDesiredStateOfWorld returns a new instance of DesiredStateOfWorld.

type PluginHandler

type PluginHandler interface {
	// Validate returns an error if the information provided by
	// the potential plugin is erroneous (unsupported version, ...)
	ValidatePlugin(pluginName string, endpoint string, versions []string) error
	// RegisterPlugin is called so that the plugin can be register by any
	// plugin consumer
	// Error encountered here can still be Notified to the plugin.
	RegisterPlugin(pluginName, endpoint string, versions []string) error
	// DeRegister is called once the pluginwatcher observes that the socket has
	// been deleted.
	DeRegisterPlugin(pluginName string)
}

PluginHandler is an interface a client of the pluginwatcher API needs to implement in order to consume plugins The PluginHandler follows the simple following state machine:

                       +--------------------------------------+
                       |            ReRegistration            |
                       | Socket created with same plugin name |
                       |                                      |
                       |                                      |
  Socket Created       v                                      +        Socket Deleted
+------------------> Validate +---------------------------> Register +------------------> DeRegister
                       +                                      +                              +
                       |                                      |                              |
                       | Error                                | Error                        |
                       |                                      |                              |
                       v                                      v                              v
                      Out                                    Out                            Out

The pluginwatcher module follows strictly and sequentially this state machine for each *plugin name*. e.g: If you are Registering a plugin foo, you cannot get a DeRegister call for plugin foo until the Register("foo") call returns. Nor will you get a Validate("foo", "Different endpoint", ...) call until the Register("foo") call returns.

ReRegistration: Socket created with same plugin name, usually for a plugin update e.g: plugin with name foo registers at foo.com/foo-1.9.7 later a plugin with name foo registers at foo.com/foo-1.9.9

DeRegistration: When ReRegistration happens only the deletion of the new socket will trigger a DeRegister call

type PluginInfo

type PluginInfo struct {
	SocketPath string
	Timestamp  time.Time
	Handler    PluginHandler
	Name       string
}

PluginInfo holds information of a plugin

func (*PluginInfo) GenerateError

func (plugin *PluginInfo) GenerateError(prefixMsg string, err error) (simpleErr, detailedErr error)

GenerateError returns simple and detailed errors for plugins to register that is user friendly and a detailed error that can be used in logs. The msg format follows the pattern "<prefixMsg> <plugin details>: <err> ".

func (*PluginInfo) GenerateErrorDetailed

func (plugin *PluginInfo) GenerateErrorDetailed(prefixMsg string, err error) (detailedErr error)

GenerateErrorDetailed returns detailed errors for plugins to register that can be used in logs. The msg format follows the pattern "<prefixMsg> <plugin details>: <err> ",

func (*PluginInfo) GenerateMsg

func (plugin *PluginInfo) GenerateMsg(prefixMsg, suffixMsg string) (simpleMsg, detailedMsg string)

GenerateMsg returns simple and detailed msgs for plugins to register that is user friendly and a detailed msg that can be used in logs. The msg format follows the pattern "<prefixMsg> <plugin details> <suffixMsg>".

func (*PluginInfo) GenerateMsgDetailed

func (plugin *PluginInfo) GenerateMsgDetailed(prefixMsg, suffixMsg string) (detailedMsg string)

GenerateMsgDetailed returns detailed msgs for plugins to register that can be used in logs. The msg format follows the pattern "<prefixMsg> <plugin details> <suffixMsg>"