view release on metacpan or  search on metacpan

lib/API/Docker/API/Volumes.pm  view on Meta::CPAN

=head1 VERSION

version 0.004

=head1 SYNOPSIS

    my $docker = API::Docker->new;

    # Create a volume
    my $volume = $docker->volumes->create(
        Name   => 'my-volume',
        Driver => 'local',
    );

    # List volumes
    my $volumes = $docker->volumes->list;

    # Inspect volume
    my $vol = $docker->volumes->inspect('my-volume');
    say $vol->mountpoint;

    # Remove volume
    $docker->volumes->remove('my-volume');

=head1 DESCRIPTION

This module provides methods for managing Docker volumes including creation,
listing, inspection, and removal.

L</list>, L</inspect> and L</create> all return
L<API::Docker::Type::Volume> objects carrying the convenience methods of
L<API::Docker::Role::Entity::Volume>, so C<< $volume->remove >> works on any
of them. The field names are the swagger's own spelling in snake_case:
C<Mountpoint> is C<< ->mountpoint >>, C<CreatedAt> is C<< ->created_at >>,
C<UsageData> is C<< ->usage_data >> and inflates into an
L<API::Docker::Type::Volume::UsageData>.

This is B<one> class for all three calls, where containers and images have
two: the swagger answers the inspect and the create with the C<Volume>
definition outright and the list with a C<VolumeListResponse> whose
C<Volumes> is an array of that same definition -- see
L<API::Docker::Role::Entity::Volume/"One class for all three calls">. A
volume is also addressed by its C<< ->name >> rather than by an id; it has
none.

Accessed via C<< $docker->volumes >>, or through
L<API::Docker::Role::Using/using> for a run of calls that needs its own
transport bound: C<< $docker->volumes->using(read_timeout => 5) >>.

=head2 client

Reference to L<API::Docker> client. Weak reference to avoid circular dependencies.

=head2 list

    my $volumes = $volumes->list;
    my $unused  = $volumes->list(filters => { dangling => ['true'] });

List volumes. Returns an ArrayRef of L<API::Docker::Type::Volume> objects,
each carrying the methods of L<API::Docker::Role::Entity::Volume>. The
daemon answers this endpoint with a C<VolumeListResponse> rather than a bare
array; the C<Volumes> key is what comes back here, and the C<Warnings>
beside it are dropped.

Options:

=over

=item * C<filters> - HashRef of filter name to ArrayRef of string values; the
engine accepts C<dangling>, C<driver>, C<label> and C<name> here.
Shape-checked and normalised by L<API::Docker::Role::Filters>

=back

=head2 create

    my $volume = $volumes->create(
        Name   => 'my-volume',
        Driver => 'local',
    );

Create a volume. Returns an L<API::Docker::Type::Volume> -- the only creating
method in this distribution that wraps its response, because the swagger
answers C<POST /volumes/create> with the same definition an inspect returns.

=head2 inspect

    my $volume = $volumes->inspect('my-volume');

Get detailed information about a volume. Returns an
L<API::Docker::Type::Volume> -- the same class L</list> and L</create>
return, since the swagger describes a volume one way.

=head2 remove

    $volumes->remove('my-volume', force => 1);

Remove a volume. Optional C<force> parameter.

=head2 prune

    my $result = $volumes->prune;
    my $result = $volumes->prune(filters => { label => ['stage=build'] });

Delete unused volumes. Returns hashref with C<VolumesDeleted> and C<SpaceReclaimed>.

Options:

=over

=item * C<filters> - HashRef of filter name to ArrayRef of string values; the
engine accepts C<label> here. Shape-checked and normalised by
L<API::Docker::Role::Filters>

=back

=head1 SEE ALSO

=over

=item * L<API::Docker> - Main Docker client