Documentation
¶
Overview ¶
Package plugin defines the Controller Hook Plugin interface for Volume lifecycle management (create / destroy / get-info / exists).
Three implementation styles are supported (mirroring the design doc):
- built-in: compiled directly into CubeMaster (this package)
- binary: CubeMaster forks an external binary with sub-commands
- network RPC: CubeMaster calls a remote gRPC/HTTP service
Only built-in plugins register via init(); binary and rpc load from config.
Index ¶
- Constants
- func LoadBinary(cfg Config) error
- func LoadRPC(cfg Config) error
- func Register(p ControllerPlugin)
- func SetBinaryFactory(f func(name, binaryPath string) ControllerPlugin)
- func SetRPCFactory(f func(name, socketPath string) (ControllerPlugin, error))
- func UnregisterForTest(name string)
- func ValidateConfigs(configs []Config) error
- type Config
- type ControllerPlugin
- type PluginType
- type VolumeInfo
Constants ¶
const BuiltinDemoPluginName = "builtin"
BuiltinDemoPluginName is the registered name of the built-in demo plugin.
Variables ¶
This section is empty.
Functions ¶
func LoadBinary ¶
LoadBinary creates and registers a binary ControllerPlugin from cfg. Returns an error if the config is invalid or the name is already registered.
func Register ¶
func Register(p ControllerPlugin)
Register adds a plugin to the global registry. Typically called from an init() function in the plugin's own file. Panics on duplicate names to catch misconfiguration at startup.
func SetBinaryFactory ¶
func SetBinaryFactory(f func(name, binaryPath string) ControllerPlugin)
SetBinaryFactory is called from plugin/binary's init() to register the constructor without creating an import cycle.
func SetRPCFactory ¶
func SetRPCFactory(f func(name, socketPath string) (ControllerPlugin, error))
SetRPCFactory is called from plugin/rpc's init() to register the constructor without creating an import cycle.
func UnregisterForTest ¶
func UnregisterForTest(name string)
UnregisterForTest removes a plugin from the global registry. Intended for tests that register ephemeral fake ControllerPlugins.
func ValidateConfigs ¶
ValidateConfigs checks volume_plugins for duplicate driver names and empty names.
Types ¶
type Config ¶
type Config struct {
// Name is the driver identifier (POST /volumes `driver`, sandbox volumeMounts routing).
// Must be unique among all volume_plugins entries; type does not disambiguate.
Name string `toml:"name" yaml:"name"`
// Type selects the implementation: "builtin", "binary", or "rpc".
Type PluginType `toml:"type" yaml:"type"`
// BinaryPath is the filesystem path to the plugin executable.
// Required when Type == PluginTypeBinary.
BinaryPath string `toml:"binary_path" yaml:"binary_path"`
// SocketPath is the Unix socket or TCP address for the gRPC server.
// Required when Type == PluginTypeRPC.
SocketPath string `toml:"socket_path" yaml:"socket_path"`
}
Config holds the configuration for one external (binary) plugin entry, as declared in the CubeMaster TOML config file.
Example:
[[volume_plugins]] name = "cos" type = "binary" binary_path = "/usr/local/services/cubetoolbox/volume-plugin/cube-volume-cos" [[volume_plugins]] name = "cos-rpc" type = "rpc" socket_path = "/run/cube-volume-cos-rpc.sock"
type ControllerPlugin ¶
type ControllerPlugin interface {
// Name returns the unique plugin identifier stored in VolumeRecord.PluginName.
Name() string
// Create allocates a new volume.
// volumeID is pre-generated by the caller (UUIDv4) so the plugin can use
// it as a stable handle during creation without a second round-trip.
Create(ctx context.Context, volumeID, name string) (*VolumeInfo, error)
// Destroy permanently deletes a volume and all its data.
Destroy(ctx context.Context, volumeID string) error
}
ControllerPlugin is the interface every Controller Hook Plugin must satisfy. It handles the management plane: create / destroy. The data plane (attach/detach) is handled by the Node Hook in Cubelet.
func Default ¶
func Default() ControllerPlugin
Default returns the built-in demo plugin used when no explicit plugin is configured. Panics if the built-in plugin was never registered.
func First ¶
func First() (ControllerPlugin, bool)
First returns the first registered plugin (in registration order). Returns (nil, false) when no plugin has been registered yet.
func Get ¶
func Get(name string) (ControllerPlugin, bool)
Get returns the named plugin, or (nil, false) if not registered.
type PluginType ¶
type PluginType string
PluginType selects the loading mechanism for a ControllerPlugin.
const ( PluginTypeBuiltin PluginType = "builtin" PluginTypeBinary PluginType = "binary" PluginTypeRPC PluginType = "rpc" )
type VolumeInfo ¶
type VolumeInfo struct {
// VolumeID is the stable identifier assigned by the plugin (or generated
// by the caller before invoking the plugin).
VolumeID string `json:"volumeID"`
// Name is the human-readable label.
Name string `json:"name"`
// Token is the auth credential used by the volume-content service.
// May be empty for backends that do not require per-volume tokens.
Token string `json:"token"`
// PrivateData is opaque plugin state persisted in t_cube_volume and
// forwarded to the Node Attach hook. Not returned to API/SDK clients.
// Max length: models.MaxPrivateDataLen (1024). May be empty.
PrivateData string `json:"privateData,omitempty"`
// PluginName identifies which plugin produced this record.
// Populated automatically by the registry before returning to the caller.
PluginName string `json:"pluginName"`
}
VolumeInfo is the canonical result returned by the plugin after a successful create or get-info call. All fields except Token and PrivateData are required.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package binary implements a ControllerPlugin that forks an external binary once per operation.
|
Package binary implements a ControllerPlugin that forks an external binary once per operation. |
|
Package rpc implements a ControllerPlugin that calls an external gRPC server.
|
Package rpc implements a ControllerPlugin that calls an external gRPC server. |