or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

container.mddocker-client.mdimage.mdindex.mdplugin.mdswarm.mdvolume-network.md
tile.json

plugin.mddocs/

Plugin Operations

Docker plugin lifecycle and configuration management. Plugins extend Docker functionality with additional capabilities like volume drivers, network drivers, and authorization plugins.

Plugin Management

Plugin Instance

Plugin objects represent Docker plugins that extend Docker functionality.

/**
 * Plugin instance representing a Docker plugin
 */
class Plugin {
  /** Plugin name */
  name: string;
  /** Docker modem instance for API communication */
  modem: any;
  
  constructor(modem: any, name: string);
}

Usage Examples:

const Docker = require('dockerode');
const docker = new Docker();

// Get plugin instance by name
const plugin = docker.getPlugin('my-plugin:latest');
const volumeDriver = docker.getPlugin('vieux/sshfs:latest');

Plugin Information

Get detailed plugin information and capabilities.

/**
 * Get plugin details and configuration
 * @param opts - Inspection options
 * @param callback - Optional callback
 * @returns Promise resolving to plugin details
 */
inspect(opts?: PluginInspectOptions, callback?: Function): Promise<PluginInspectInfo>;

/**
 * Get plugin required privileges
 * @param opts - Privileges options
 * @param callback - Optional callback
 * @returns Promise resolving to privilege list
 */
privileges(opts?: PluginPrivilegesOptions, callback?: Function): Promise<PluginPrivilege[]>;

interface PluginInspectOptions {
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginPrivilegesOptions {
  /** Plugin remote reference */
  remote?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginInspectInfo {
  Id: string;
  Name: string;
  Enabled: boolean;
  Settings: PluginSettings;
  PluginReference: string;
  Config: PluginConfig;
}

interface PluginSettings {
  Mounts: PluginMount[];
  Env: string[];
  Args: string[];
  Devices: PluginDevice[];
}

interface PluginConfig {
  DockerVersion?: string;
  Description: string;
  Documentation: string;
  Interface: PluginInterface;
  Entrypoint: string[];
  WorkDir: string;
  User?: PluginUser;
  Network: PluginNetwork;
  Linux: PluginLinux;
  PropagatedMount: string;
  IpcHost: boolean;
  PidHost: boolean;
  Mounts: PluginMount[];
  Env: PluginEnv[];
  Args: PluginArgs;
  rootfs?: {
    type?: string;
    diff_ids?: string[];
  };
}

interface PluginInterface {
  Types: PluginInterfaceType[];
  Socket: string;
  ProtocolScheme?: string;
}

interface PluginInterfaceType {
  Prefix: string;
  Capability: string;
  Version: string;
}

interface PluginPrivilege {
  Name: string;
  Description: string;
  Value: string[];
}

Usage Examples:

// Get plugin details
const pluginInfo = await plugin.inspect();
console.log(`Plugin: ${pluginInfo.Name}`);
console.log(`Enabled: ${pluginInfo.Enabled}`);
console.log(`Description: ${pluginInfo.Config.Description}`);

// Check plugin capabilities
pluginInfo.Config.Interface.Types.forEach(type => {
  console.log(`Capability: ${type.Capability} (${type.Version})`);
});

// Get plugin privileges
const privileges = await plugin.privileges({ remote: 'vieux/sshfs:latest' });
privileges.forEach(priv => {
  console.log(`Privilege: ${priv.Name} - ${priv.Description}`);
  console.log(`Values: ${priv.Value.join(', ')}`);
});

Plugin Lifecycle

Control plugin installation, enabling, disabling, and removal.

/**
 * Install plugin from repository
 * @param opts - Pull options
 * @param callback - Optional callback
 * @returns Promise resolving to pull stream
 */
pull(opts?: PluginPullOptions, callback?: Function): Promise<Stream>;

/**
 * Enable installed plugin
 * @param opts - Enable options
 * @param callback - Optional callback
 * @returns Promise resolving to enable result
 */
enable(opts?: PluginEnableOptions, callback?: Function): Promise<object>;

/**
 * Disable active plugin
 * @param opts - Disable options
 * @param callback - Optional callback
 * @returns Promise resolving to disable result
 */
disable(opts?: PluginDisableOptions, callback?: Function): Promise<object>;

/**
 * Remove plugin
 * @param opts - Remove options
 * @param callback - Optional callback
 * @returns Promise resolving to remove result
 */
remove(opts?: PluginRemoveOptions, callback?: Function): Promise<object>;

/**
 * Upgrade plugin to newer version
 * @param auth - Registry authentication
 * @param opts - Upgrade options
 * @param callback - Optional callback
 * @returns Promise resolving to upgrade stream
 */
upgrade(auth?: object, opts?: PluginUpgradeOptions, callback?: Function): Promise<Stream>;

interface PluginPullOptions {
  /** Plugin privileges */
  privileges?: PluginPrivilege[];
  /** Plugin name */
  name?: string;
  /** Plugin remote reference */
  remote?: string;
  /** Registry authentication */
  authconfig?: AuthConfig;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginEnableOptions {
  /** Plugin timeout */
  timeout?: number;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginDisableOptions {
  /** Force disable */
  force?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginRemoveOptions {
  /** Force removal */
  force?: boolean;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginUpgradeOptions {
  /** Plugin privileges */
  privileges?: PluginPrivilege[];
  /** Plugin remote reference */
  remote?: string;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

Usage Examples:

// Install plugin
const pullStream = await plugin.pull({
  remote: 'vieux/sshfs:latest',
  privileges: [
    {
      Name: 'network',
      Description: 'Allow plugin to access host network',
      Value: ['host']
    }
  ]
});

pullStream.on('data', chunk => {
  const progress = JSON.parse(chunk.toString());
  console.log(progress.status || progress.id);
});

// Enable plugin
await plugin.enable({ timeout: 30 });

// Check if plugin is enabled
const info = await plugin.inspect();
console.log(`Plugin enabled: ${info.Enabled}`);

// Disable plugin
await plugin.disable({ force: false });

// Upgrade plugin
const upgradeStream = await plugin.upgrade(undefined, {
  remote: 'vieux/sshfs:v1.2.0',
  privileges: []
});

// Remove plugin
await plugin.remove({ force: true });

Plugin Operations

Additional plugin management operations.

/**
 * Push plugin to repository
 * @param opts - Push options
 * @param callback - Optional callback
 * @returns Promise resolving to push stream
 */
push(opts?: PluginPushOptions, callback?: Function): Promise<Stream>;

/**
 * Configure plugin settings
 * @param opts - Configuration options
 * @param callback - Optional callback
 * @returns Promise resolving to configure result
 */
configure(opts: PluginConfigureOptions, callback?: Function): Promise<object>;

interface PluginPushOptions {
  /** Registry authentication */
  authconfig?: AuthConfig;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginConfigureOptions {
  /** Plugin configuration settings */
  Settings?: PluginSettings;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

Usage Examples:

// Configure plugin settings
await plugin.configure({
  Settings: {
    Env: ['DEBUG=1', 'LOG_LEVEL=info'],
    Args: ['--verbose'],
    Mounts: [
      {
        Name: 'config',
        Description: 'Plugin configuration',
        Settable: ['source'],
        Source: '/etc/plugin-config',
        Destination: '/config',
        Type: 'bind',
        Options: ['rbind']
      }
    ],
    Devices: []
  }
});

// Push plugin to registry
const pushStream = await plugin.push({
  authconfig: {
    username: 'myuser',
    password: 'mypass',
    serveraddress: 'https://index.docker.io/v1/'
  }
});

pushStream.on('data', chunk => {
  const progress = JSON.parse(chunk.toString());
  console.log(progress.status);
});

Plugin Creation and Management (Docker Client)

Plugin creation and listing operations available on the Docker client.

/**
 * Create a new plugin (available on Docker client)
 * @param opts - Plugin creation options
 * @param callback - Optional callback
 * @returns Promise resolving to Plugin instance
 */
docker.createPlugin(opts: PluginCreateOptions, callback?: Function): Promise<Plugin>;

/**
 * List plugins with filtering options (available on Docker client)
 * @param opts - Filtering and query options
 * @param callback - Optional callback
 * @returns Promise resolving to plugin list
 */
docker.listPlugins(opts?: ListPluginsOptions, callback?: Function): Promise<PluginInfo[]>;

interface PluginCreateOptions {
  /** Plugin name */
  name: string;
  /** Plugin tar data */
  plugindata: Stream;
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface ListPluginsOptions {
  /** Plugin filters */
  filters?: {
    /** Filter by capability */
    capability?: string[];
    /** Filter by enabled status */
    enabled?: boolean[];
  };
  /** AbortSignal for request cancellation */
  abortSignal?: AbortSignal;
}

interface PluginInfo {
  Id: string;
  Name: string;
  Enabled: boolean;
  Settings: PluginSettings;
  PluginReference: string;
  Config: PluginConfig;
}

Usage Examples:

const tar = require('tar-fs');
const fs = require('fs');

// Create plugin from local directory
const pluginTar = tar.pack('./my-plugin');
const plugin = await docker.createPlugin({
  name: 'my-custom-plugin:latest',
  plugindata: pluginTar
});

// List all plugins
const plugins = await docker.listPlugins();
plugins.forEach(p => {
  console.log(`${p.Name}: ${p.Enabled ? 'enabled' : 'disabled'}`);
  p.Config.Interface.Types.forEach(type => {
    console.log(`  - ${type.Capability}`);
  });
});

// List only enabled volume driver plugins
const volumeDrivers = await docker.listPlugins({
  filters: {
    capability: ['volumedriver'],
    enabled: [true]
  }
});

console.log('Enabled volume drivers:');
volumeDrivers.forEach(driver => {
  console.log(`- ${driver.Name}`);
});

Plugin Types and Use Cases

Common plugin types and their typical use cases.

Volume Driver Plugins:

// Install and configure a volume driver plugin
const sshfsPlugin = docker.getPlugin('vieux/sshfs:latest');

await sshfsPlugin.pull({
  privileges: [
    {
      Name: 'network',
      Description: 'Allow plugin to access host network',
      Value: ['host']
    },
    {
      Name: 'mount',
      Description: 'Allow plugin to mount directories',
      Value: ['/var/lib/docker/plugins/']
    }
  ]
});

await sshfsPlugin.enable();

// Create volume using the plugin
const sshfsVolume = await docker.createVolume({
  Name: 'remote-data',
  Driver: 'vieux/sshfs:latest',
  DriverOpts: {
    sshcmd: 'user@server:/remote/path',
    password: 'secret'
  }
});

Network Driver Plugins:

// List network driver plugins
const networkPlugins = await docker.listPlugins({
  filters: {
    capability: ['networkdriver'],
    enabled: [true]
  }
});

// Create network using custom driver
const customNetwork = await docker.createNetwork({
  Name: 'overlay-network',
  Driver: 'my-custom-driver',
  Options: {
    'custom.option1': 'value1',
    'custom.option2': 'value2'
  }
});

Authorization Plugins:

// Enable authorization plugin
const authPlugin = docker.getPlugin('my-auth-plugin:latest');
await authPlugin.enable();

// Plugin will now intercept all Docker API calls for authorization

Plugin Development

Interface definitions for plugin development.

interface PluginMount {
  Name: string;
  Description: string;
  Settable: string[];
  Source: string;
  Destination: string;
  Type: string;
  Options: string[];
}

interface PluginDevice {
  Name: string;
  Description: string;
  Settable: string[];
  Path: string;
}

interface PluginEnv {
  Name: string;
  Description: string;
  Settable: string[];
  Value: string;
}

interface PluginArgs {
  Name: string;
  Description: string;
  Settable: string[];
  Value: string[];
}

interface PluginUser {
  UID: number;
  GID: number;
}

interface PluginNetwork {
  Type: string;
}

interface PluginLinux {
  Capabilities: string[];
  AllowAllDevices: boolean;
  Devices: PluginDevice[];
}

Plugin Configuration Example:

// Example plugin config.json structure
const pluginConfig = {
  "description": "My custom volume driver",
  "documentation": "https://docs.example.com/plugin",
  "interface": {
    "types": ["docker.volumedriver/1.0"],
    "socket": "plugin.sock"
  },
  "entrypoint": ["/usr/bin/my-plugin"],
  "workdir": "/app",
  "network": {
    "type": "host"
  },
  "mounts": [
    {
      "source": "/var/lib/docker/plugins/",
      "destination": "/mnt/state",
      "type": "bind",
      "options": ["rbind", "rshared"]
    }
  ],
  "env": [
    {
      "name": "DEBUG",
      "settable": ["value"],
      "value": "0"
    }
  ],
  "args": {
    "name": "args",
    "settable": ["value"],
    "value": []
  }
};