/ 
API-Docker-0.004
/ API::Docker::Role::Entity::Plugin

NAME

API::Docker::Role::Entity::Plugin - Plugin operations, on the generated plugin type

VERSION

version 0.004

SYNOPSIS

my $docker = API::Docker->new;
my ($plugin) = @{ $docker->plugins->list };

say $plugin->name;
say $plugin->enabled ? 'enabled' : 'disabled';
say join ', ', @{ $plugin->settings->env };

$plugin->disable;
$plugin->configure(['DEBUG=1']);
$plugin->enable;

DESCRIPTION

The convenience methods of a Docker managed plugin. This role is composed, at load time, into API::Docker::Type::Plugin, the generated class the daemon answers plugin requests with -- the same definition for GET /plugins and GET /plugins/{name}/json, so "list" in API::Docker::API::Plugins and "inspect" in API::Docker::API::Plugins hand back one class and there is no list-versus-inspect shape to keep apart.

The entity is addressed by name, not by id

Every method here threads ->name through to the method of the same name on API::Docker::API::Plugins, so the options, the return values and the failure modes are that class's -- documented there, not repeated here. The class does carry an ->id, but the endpoints route on the name, which is why this role requires 'name'.

->name is the plugin as it is installed locally -- vieux/sshfs:latest, or whatever local name "install" in API::Docker::API::Plugins was given. The remote it came from is ->plugin_reference (docker.io/vieux/sshfs:latest), which the engine sets on the pull, upgrade and create paths only and omits entirely otherwise rather than sending it as null -- so it reads as undef for a plugin that never came from a registry, and differs from the name outright for one installed under a local one. That is exactly the case where "upgrade" needs remote spelled out.

Two shapes of Env, one level apart

$plugin->settings->env is a list of KEY=value strings, which is what "configure" takes. $plugin->config->env is a list of API::Docker::Type::PluginEnv objects describing those same variables -- same field name, two shapes. The daemon flattens the one into the other when the plugin is installed. "configure" writes to the settings, never to the config.

Not available on Podman

Managed plugins are a Docker feature: none of these endpoints exist on Podman, so nothing in this role works against it. See "Not available on Podman" in API::Docker::API::Plugins.

Why the methods are a role applied to a generated class rather than a class of their own: "DESCRIPTION" in API::Docker::Role::Entity.

inspect

my $fresh = $plugin->inspect;

Get fresh plugin information. Returns another API::Docker::Type::Plugin -- the same class, since the daemon describes a plugin one way.

enable

$plugin->enable;
$plugin->enable(timeout => 30);

Enable the plugin.

disable

$plugin->disable(force => 1);

Disable the plugin.

remove

$plugin->remove(force => 1);

Remove the plugin. An enabled plugin is refused without force.

configure

$plugin->configure(['DEBUG=1']);
$plugin->configure('DEBUG=1', 'sshkey.source=/tmp');

Set the plugin's user-configurable settings. The plugin must be disabled first. The settings are the KEY=value strings of $plugin->settings->env, not the objects of $plugin->config->env -- see "Two shapes of Env, one level apart".

upgrade

my $privileges = $docker->plugins->privileges($plugin->plugin_reference);
$plugin->upgrade(remote => $plugin->plugin_reference,
    privileges => $privileges);

Upgrade the plugin in place. privileges is required, as it is on "upgrade" in API::Docker::API::Plugins, and remote defaults to "name" in API::Docker::Type::Plugin -- which is not what you want for a plugin installed under a local name, hence ->plugin_reference.

push

$plugin->push(auth => { username => 'me', password => 'secret' });

Push the plugin to a registry. This writes to a real registry under the credentials given.

push shadows the Perl builtin inside this package, which is why namespace::clean is loaded. Always call it as a method.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-api-docker/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.