API-Docker
view release on metacpan or search on metacpan
lib/API/Docker/API/Containers.pm view on Meta::CPAN
return 1;
}
sub list {
my ($self, %opts) = @_;
my %params;
$params{all} = $opts{all} ? 1 : 0 if defined $opts{all};
$params{limit} = $opts{limit} if defined $opts{limit};
$params{size} = $opts{size} ? 1 : 0 if defined $opts{size};
$params{filters} = $self->_normalise_filters($opts{filters})
if defined $opts{filters};
my $result = $self->client->get('/containers/json',
params => \%params,
%{ $self->_request_options },
);
return $self->_wrap_list('API::Docker::Type::ContainerSummary', $result // []);
}
# The booleans of the container create body, from spec/v1.51.yaml: the
# ContainerConfig flags at the top level, and the HostConfig flags in the
# nested `HostConfig` object (its own plus the ones it inherits from
# Resources). The engine rejects a number for any of them, so 1/0 is
# normalised to a JSON boolean on the way out; a caller may still pass 1/0 or a
# JSON boolean and it goes out correctly either way.
my @CONTAINER_CONFIG_BOOLS = qw(
ArgsEscaped AttachStderr AttachStdin AttachStdout NetworkDisabled
OpenStdin StdinOnce Tty
);
my @HOST_CONFIG_BOOLS = qw(
AutoRemove Init OomKillDisable Privileged PublishAllPorts ReadonlyRootfs
);
sub create {
my ($self, %config) = @_;
my %params;
$params{name} = delete $config{name} if defined $config{name};
$self->_json_bools(\%config, @CONTAINER_CONFIG_BOOLS);
# Copy the nested HostConfig before touching it -- _json_bools mutates, and
# the sub-object is still the caller's until this copy replaces it.
if (ref $config{HostConfig} eq 'HASH') {
my %host_config = %{ $config{HostConfig} };
$self->_json_bools(\%host_config, @HOST_CONFIG_BOOLS);
$config{HostConfig} = \%host_config;
}
my $result = $self->client->post('/containers/create', \%config, params => \%params);
return $result;
}
sub inspect {
my ($self, $id) = @_;
croak "Container ID required" unless $id;
my $result = $self->client->get("/containers/$id/json",
%{ $self->_request_options },
);
return $self->_wrap('API::Docker::Type::ContainerInspectResponse', $result);
}
sub start {
my ($self, $id) = @_;
croak "Container ID required" unless $id;
return $self->_state_change("/containers/$id/start",
%{ $self->_request_options },
);
}
sub stop {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
my %params;
$params{t} = $opts{timeout} if defined $opts{timeout};
$params{signal} = $opts{signal} if defined $opts{signal};
return $self->_state_change("/containers/$id/stop",
params => \%params,
%{ $self->_request_options },
);
}
sub restart {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
my %params;
$params{t} = $opts{timeout} if defined $opts{timeout};
return $self->_state_change("/containers/$id/restart",
params => \%params,
%{ $self->_request_options },
);
}
sub kill {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
my %params;
$params{signal} = $opts{signal} if defined $opts{signal};
return $self->client->post("/containers/$id/kill", undef,
params => \%params,
%{ $self->_request_options },
);
}
sub remove {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
my %params;
$params{v} = $opts{volumes} ? 1 : 0 if defined $opts{volumes};
$params{force} = $opts{force} ? 1 : 0 if defined $opts{force};
$params{link} = $opts{link} ? 1 : 0 if defined $opts{link};
return $self->client->delete_request("/containers/$id",
params => \%params,
%{ $self->_request_options },
);
}
sub logs {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
my %params;
$params{follow} = $opts{follow} ? 1 : 0 if defined $opts{follow};
$params{stdout} = defined $opts{stdout} ? ($opts{stdout} ? 1 : 0) : 1;
$params{stderr} = defined $opts{stderr} ? ($opts{stderr} ? 1 : 0) : 1;
$params{since} = $opts{since} if defined $opts{since};
$params{until} = $opts{until} if defined $opts{until};
$params{timestamps} = $opts{timestamps} ? 1 : 0 if defined $opts{timestamps};
$params{tail} = $opts{tail} if defined $opts{tail};
# exists, not truth: an unset callback is a caller bug, and quietly falling
# back to the buffered path for it would answer a follow with a hang.
return $self->client->stream_frames('GET', "/containers/$id/logs",
params => \%params,
defined $opts{tty} ? ( tty => $opts{tty} ) : (),
%{ $self->_request_options },
exists $opts{on_frame} ? ( on_frame => $opts{on_frame} ) : (),
);
}
# The guard behind attach's require_running, and a pre-flight check is all it
# is: it asks the engine what the container is doing now, and the container may
# still stop between that answer and the attach landing. That race is not
# closable from a client -- the engine offers no attach-if-running -- and the
# check earns its round trip anyway, because the condition it tests is exactly
# the condition that does the damage. Measured on Podman 5.4.2 (API 1.41) and
lib/API/Docker/API/Containers.pm view on Meta::CPAN
raw => 1,
%{ $self->_request_options },
);
}
sub resize {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
my %params;
$params{h} = $opts{h} if defined $opts{h};
$params{w} = $opts{w} if defined $opts{w};
return $self->client->post("/containers/$id/resize", undef,
params => \%params,
%{ $self->_request_options },
);
}
sub wait {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
my %params;
$params{condition} = $opts{condition} if defined $opts{condition};
return $self->client->post("/containers/$id/wait", undef,
params => \%params,
%{ $self->_request_options },
);
}
sub pause {
my ($self, $id) = @_;
croak "Container ID required" unless $id;
return $self->_state_change("/containers/$id/pause",
%{ $self->_request_options },
);
}
sub unpause {
my ($self, $id) = @_;
croak "Container ID required" unless $id;
return $self->_state_change("/containers/$id/unpause",
%{ $self->_request_options },
);
}
sub rename {
my ($self, $id, $name) = @_;
croak "Container ID required" unless $id;
croak "New name required" unless $name;
return $self->client->post("/containers/$id/rename", undef,
params => { name => $name },
%{ $self->_request_options },
);
}
# The update body is Resources + RestartPolicy; the booleans are the two
# Resources flags. Normalised on the way out, as for create.
my @UPDATE_BOOLS = qw( Init OomKillDisable );
sub update {
my ($self, $id, %config) = @_;
croak "Container ID required" unless $id;
$self->_json_bools(\%config, @UPDATE_BOOLS);
return $self->client->post("/containers/$id/update", \%config);
}
# The engine reports what a path is in a response header rather than a body,
# so both GET and HEAD carry it and only HEAD has nothing else to say. The
# header is base64-encoded JSON; handing the caller the base64 would make
# every one of them write this.
sub _decode_path_stat {
my ($self, $response) = @_;
my $header = $response->{headers}{'x-docker-container-path-stat'};
return undef unless defined $header && length $header;
# Docker encodes this one with Go's base64.StdEncoding -- unlike
# X-Registry-Auth, which is URLEncoding. Decoded tolerantly rather than
# strictly: translating the two URL-safe characters first costs nothing and
# means an engine that reached for the other alphabet is still read.
$header =~ tr{-_}{+/};
my $stat = eval { decode_json(decode_base64($header)) };
croak "Cannot decode X-Docker-Container-Path-Stat header: $@"
unless ref $stat eq 'HASH';
return $stat;
}
sub get_archive {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
croak "Path required" unless defined $opts{path} && length $opts{path};
croak "The stat option must be a HashRef"
if exists $opts{stat} && ref $opts{stat} ne 'HASH';
my %response;
my $tar = $self->client->get("/containers/$id/archive",
params => { path => $opts{path} },
raw => 1,
response => \%response,
%{ $self->_request_options },
);
if (my $out = $opts{stat}) {
%$out = %{ $self->_decode_path_stat(\%response) // {} };
}
return $tar;
}
sub put_archive {
my ($self, $id, $tar, %opts) = @_;
croak "Container ID required" unless $id;
croak "Path required" unless defined $opts{path} && length $opts{path};
lib/API/Docker/API/Containers.pm view on Meta::CPAN
);
}
sub stat_archive {
my ($self, $id, %opts) = @_;
croak "Container ID required" unless $id;
croak "Path required" unless defined $opts{path} && length $opts{path};
my %response;
$self->client->head("/containers/$id/archive",
params => { path => $opts{path} },
response => \%response,
%{ $self->_request_options },
);
return $self->_decode_path_stat(\%response);
}
sub prune {
my ($self, %opts) = @_;
my %params;
$params{filters} = $self->_normalise_filters($opts{filters})
if defined $opts{filters};
return $self->client->post('/containers/prune', undef,
params => \%params,
%{ $self->_request_options },
);
}
1;
__END__
=pod
=encoding UTF-8
=head1 NAME
API::Docker::API::Containers - Docker Engine Containers API
=head1 VERSION
version 0.004
=head1 SYNOPSIS
my $docker = API::Docker->new;
# List containers
my $containers = $docker->containers->list(all => 1);
for my $container (@$containers) {
say $container->id;
say $container->status;
}
# Create and start a container
my $result = $docker->containers->create(
Image => 'nginx:latest',
name => 'my-nginx',
ExposedPorts => { '80/tcp' => {} },
);
$docker->containers->start($result->{Id});
# Inspect container details
my $container = $docker->containers->inspect($result->{Id});
say $container->name;
# Stop and remove
$docker->containers->stop($result->{Id}, timeout => 10);
$docker->containers->remove($result->{Id});
# View logs (ArrayRef of { stream => 'stdout'|'stderr'|'raw', data => ... })
my $frames = $docker->containers->logs($result->{Id}, tail => 100);
my $text = join '', map { $_->{data} } @$frames;
# Attach one-way: replays the same frames and returns (stream => 0 by
# default -- stream => 1 on a stopped container never returns). On Podman,
# attaching to a container that has ALREADY EXITED destroys its exit
# status; use logs() for that case, see attach()
my $attached = $docker->containers->attach($result->{Id});
# Copy a file out, and a tar archive in (what docker cp is built on)
my $tar = $docker->containers->get_archive($result->{Id},
path => '/etc/hostname');
$docker->containers->put_archive($result->{Id}, $tar, path => '/tmp');
=head1 DESCRIPTION
This module provides methods for managing Docker containers including creation,
lifecycle operations (start, stop, restart), inspection, logs, and more.
C<list> and C<inspect> return generated L<API::Docker::Type> objects carrying
the convenience methods of L<API::Docker::Role::Entity::Container>, so
C<< $container->start >> and C<< $container->logs >> work on either. Which
class each returns, and where the two disagree, is below.
Accessed via C<< $docker->containers >>, or through
L<API::Docker::Role::Using/using> for a run of calls that needs its own
transport bound: C<< $docker->containers->using(read_timeout => 5) >>.
=head2 The two container shapes
The daemon describes a container two ways and the swagger has two
definitions for it, so this class returns two classes:
=over
=item * L</list> returns L<API::Docker::Type::ContainerSummary> objects --
one per entry of C<GET /containers/json>.
=item * L</inspect> returns an L<API::Docker::Type::ContainerInspectResponse>
-- the body of C<GET /containers/{id}/json>.
=back
They overlap but do not line up, and the field names are the swagger's own
spelling in snake_case (C<Id> is C<< ->id >>, C<SizeRootFs> is
C<< ->size_root_fs >>). The differences worth knowing before reading a value
off the wrong one:
=over
=item * C<< ->image >> is the name the container was created from on a
summary (C<nginx:latest>) and the resolved C<sha256:> digest on an inspect.
A summary reports that digest separately as C<< ->image_id >>; an inspect
has no such field.
=item * C<< ->created >> is an integer Unix epoch on a summary and an
RFC 3339 string on an inspect. Same field name, two types -- C<Int> and
C<Str> in the model, which is the swagger's own answer, not a normalisation
this client applies.
=item * C<< ->state >> is the status string (C<running>, C<exited>) on a
summary and an L<API::Docker::Type::ContainerState> object on an inspect,
where that string is C<< ->state->status >> and the flags are
C<< ->state->running >>, C<< ->state->paused >>, C<< ->state->exit_code >>.
L<API::Docker::Role::Entity::Container/is_running> reads whichever it is
given. C<< ->status >> -- the human sentence, C<"Up 2 hours"> -- is on the
summary only.
=item * C<< ->command >> is the whole command as one string, on a summary
only. An inspect splits it into C<< ->path >> and C<< ->args >> and keeps
the original C<Cmd> ArrayRef under C<< ->config->cmd >>.
=item * C<< ->labels >> and C<< ->ports >> are top-level on a summary only.
An inspect carries the labels under C<< ->config->labels >> and the port
bindings under C<< ->network_settings->ports >>, which is a map of container
port to host bindings rather than the summary's ArrayRef of
L<API::Docker::Type::Port>.
=item * C<< ->names >> (an ArrayRef, each with a leading C</>) is the
summary's; C<< ->name >> (one string, also with the C</>) is the inspect's.
=item * C<< ->config >>, C<< ->restart_count >>, C<< ->driver >>,
C<< ->platform >>, C<< ->graph_driver >>, C<< ->exec_ids >> and the
C<*_path> fields come from an inspect only.
=item * C<< ->host_config >> and C<< ->network_settings >> exist on both and
are B<different classes>: the summary's are
L<API::Docker::Type::ContainerSummary::HostConfig> (C<NetworkMode> and
C<Annotations>, nothing else) and
L<API::Docker::Type::ContainerSummary::NetworkSettings> (C<Networks> alone),
against the full L<API::Docker::Type::HostConfig> and
L<API::Docker::Type::NetworkSettings> on an inspect.
=item * C<< ->size_rw >> and C<< ->size_root_fs >> are on both, but a
summary only carries them when C<< size => 1 >> was asked for.
=back
A field neither class knows -- a newer engine than the C<spec/v1.51.yaml>
this model was generated from -- is not dropped: it stays under the name it
arrived with in L<API::Docker::Role::Type/unknown_fields> and goes back out
unchanged.
A field whose B<value> disagrees with the swagger is kept the same way and
costs only itself. An engine answering C<State> with the bare status string
rather than the object the spec declares leaves C<< ->state >> C<undef> while
every other field of the inspect reads normally; the raw value is in
C<unknown_fields> under C<State>, and
L<API::Docker::Role::Type/rejected_fields> names it, so "not sent" and "sent
and not usable" are two different answers.
=head2 client
Reference to L<API::Docker> client. Weak reference to avoid circular dependencies.
=head2 list
my $containers = $containers->list(%opts);
List containers. Returns an ArrayRef of
L<API::Docker::Type::ContainerSummary> objects -- see L</"The two container
shapes"> for what a summary carries and L</inspect> does not.
Options:
=over
=item * C<all> - Show all containers (default shows just running)
=item * C<limit> - Limit results to N most recently created containers
=item * C<size> - Include size information
=item * C<filters> - HashRef of filter name to ArrayRef of string values, e.g.
C<< { status => ['running'], label => ['stage=build'] } >>. Shape-checked and
normalised by L<API::Docker::Role::Filters>
=back
=head2 create
my $result = $containers->create(
Image => 'nginx:latest',
name => 'my-nginx',
Cmd => ['/bin/sh'],
Env => ['FOO=bar'],
);
Create a new container. Returns hashref with C<Id> and C<Warnings>.
The C<name> parameter is extracted and passed as query parameter. All other
parameters are Docker container configuration (see Docker API documentation).
Common config keys: C<Image>, C<Cmd>, C<Env>, C<ExposedPorts>, C<HostConfig>.
Boolean flags may be given as a Perl C<1>/C<0> or as a JSON boolean; either
goes out as a real JSON C<true>/C<false>, which the engine's body type-check
requires. This applies to the top-level flags (C<Tty>, C<OpenStdin>,
C<AttachStdin>, C<AttachStdout>, C<AttachStderr>, C<StdinOnce>,
C<NetworkDisabled>, C<ArgsEscaped>) and to the C<HostConfig> flags
(C<Privileged>, C<PublishAllPorts>, C<ReadonlyRootfs>, C<AutoRemove>, C<Init>,
C<OomKillDisable>).
=head2 inspect
my $container = $containers->inspect($id);
Get detailed information about a container. Returns an
L<API::Docker::Type::ContainerInspectResponse> -- see L</"The two container
shapes">.
=head2 start
$containers->start($id);
say 'was already running' unless $containers->start($id);
Start a container. Returns 1 when the container was started and 0 when it was
already running: the engine answers a state change with 204 and a no-op with
B<304 Not Modified>, and both carry an empty body, so until now both came back
as C<undef>.
The no-op keeps the falsy value this method always returned -- 0 where it used
to be C<undef> -- so a caller that ignores the return or tests it for falseness
is unaffected; only a caller testing C<defined> sees a difference. A failure is
still a croak, never a 0.
=head2 stop
$containers->stop($id, timeout => 10);
say 'was already stopped' unless $containers->stop($id);
Stop a container. Returns 1 when the container was stopped and 0 when it was
already stopped -- the engine answers the no-op with B<304 Not Modified>. See
L</start> for what that 0 replaces.
Options:
=over
=item * C<timeout> - Seconds to wait before killing (default 10)
=item * C<signal> - Signal to send (default SIGTERM)
=back
=head2 restart
$containers->restart($id, timeout => 10);
Restart a container. Optionally specify C<timeout> in seconds.
Reports 1/0 like L</start>, but a restart has no no-op state to report: the
engine restarts a stopped container as readily as a running one. Measured
against Podman 5.4.2 (API 1.41) it answers 204 in both cases, and the Docker
Engine API documents no 304 for this endpoint either, so 0 is not expected
here. The value is reported the same way rather than specially, so an engine
that does answer 304 is not silently read as a change.
=head2 kill
$containers->kill($id, signal => 'SIGKILL');
$containers->kill($id, signal => 'SIGUSR1'); # not necessarily a stop
Send a signal to a container. Default signal is C<SIGKILL>.
Returns nothing -- unlike L</start>, L</stop>, L</restart>, L</pause> and
L</unpause>, which report 1/0 through their shared C<_state_change> path.
Those methods have two outcomes worth telling apart: a change (204) and a
no-op (304, where the engine sends one). C<kill> has only one, because
C<_request> croaks on any C<< status >= 400 >>, so the B<409> a non-running
container gets back never reaches this method's C<return>. A boolean with a
single possible value is not worth adding.
More importantly, B<204 does not mean the container stopped.> Measured on
B<both> engines -- Docker 29.7.2 (API 1.55) and rootless Podman 5.4.2 (API
1.41), same machine, identical behavior: sending a signal the container traps
or ignores -- C<< signal => 'SIGUSR1' >> against a process with a handler
installed for it -- is delivered, the container keeps running, the handler's
output turns up in L</logs>, and the engine still answers 204 exactly as it
does for a signal that does end the process. A caller that needs to know
whether the container is still running after a C<kill> has to ask
L</inspect>; that is also why this returns nothing rather than a plain C<1>
-- a 1 here would claim a state change that a trapped signal never made.
B<A paused container is where the two engines part.> Both answer 204 to
C<< signal => 'SIGUSR1' >> against a paused container, and then:
=over
=item * B<Docker unpauses it as a side effect.> L</inspect> reports C<running>
straight afterwards and the handler has already run. A caller that paused the
container and means to unpause it later gets a croak instead: the following
L</unpause> answers B<500> C<Container E<lt>idE<gt> is not paused>
=item * B<Podman leaves it paused> and queues the signal. The state stays
C<paused>, the handler produces nothing until an explicit L</unpause>, and
that L</unpause> succeeds
=back
So C<kill> is a state change for a paused container on Docker and is not one
on Podman -- with the same 204 on both.
Killing a container that is not running -- stopped, exited or just created --
croaks B<409>; it does not return a falsy value. An unknown container ID
croaks B<404>. Neither is reachable through a return value, and no case
answers 304: moby's swagger for this endpoint (C<operationId: ContainerKill>)
documents only 204, 404, 409 and 500.
The B<text> of either is engine prose, so branch on
L<API::Docker::Error::HTTP/status> and not on the message. For one and the
same stopped container:
=over
=item * Docker -- C<cannot kill container: E<lt>nameE<gt>: container E<lt>idE<gt> is
not running>
=item * Podman -- C<can only kill running containers. E<lt>idE<gt> is in state
exited: container state improper>. C<container state improper> is Podman's
separate C<cause> field, reachable as C<< $err->data->{cause} >>, not a
phrase Docker uses anywhere
=back
The 404 differs too, and on Docker it differs I<per endpoint>: C<kill>
lib/API/Docker/API/Containers.pm view on Meta::CPAN
$containers->resize($id, h => 40, w => 120);
Resize the TTY of a container, so a program inside it sees the new terminal
size. Form-identical to L<API::Docker::API::Exec/resize>, which resizes the
TTY of an exec instance instead.
Only meaningful for a container created with C<< Tty => 1 >>; the engine
rejects the call otherwise.
Options:
=over
=item * C<h> - New height in character rows
=item * C<w> - New width in character columns
=back
=head2 wait
my $result = $containers->wait($id);
my $code = $result->{StatusCode};
$containers->wait($id, condition => 'not-running');
Block until the container reaches a condition, then return B<a HashRef> --
not the exit code. C<StatusCode> is the exit status of the container's main
process, and it is the one key both engines always send:
{ StatusCode => 4 } # Docker 29.7.2 (API 1.55)
{ StatusCode => 4, Error => undef } # Podman 5.4.2 (API 1.41)
B<The C<Error> key diverges, and C<exists> is the wrong test for it.>
Measured on successful waits on both engines: Docker B<omits> the key
entirely, Podman sends C<"Error": null> on every wait, which decodes to
C<undef>. So C<< exists $result->{Error} >> is false on Docker and true on
Podman for one and the same outcome, while C<< defined $result->{Error} >> is
false on both. Ask C<defined>, never C<exists>, and take C<StatusCode> as the
answer.
A B<non-null> C<Error> was not produced on either engine by any probe behind
this documentation. The Engine API reference documents it as an object
carrying C<Message>; that shape is B<documented but not measured here>, which
is not the same as unreachable -- do not write code that assumes it cannot
appear, and do not trust its shape without checking.
The call blocks in the client for as long as the engine takes to answer: this
endpoint answers only once the condition is met, and the whole response is
read before anything is parsed. There is no timeout, on this method or in the
transport.
Measured on both engines:
=over
=item * A container that has B<already exited> answers immediately with its
real exit status -- with no condition and with C<not-running> alike
=item * A container that was B<created and never started> answers immediately
with an invented one: Docker C<< StatusCode => 0 >>, Podman
C<< StatusCode => -1 >>. There is no exit status to report and the two
engines make up different ones, so a C<0> from this call is not proof that
anything ran
=item * C<< condition => 'next-exit' >> and C<< condition => 'removed' >>
against an exited container B<block> on both engines: the awaited event is in
the future and may never happen
=item * An unrecognised condition croaks B<400> on both (Docker C<invalid
condition: "...">, Podman C<failed to parse query parameter 'condition' ...>),
and an unknown container ID croaks B<404>
=back
Podman also answers C<< StatusCode => -1 >> for a container whose exit status
L</attach> has destroyed -- see
L</"On Podman this destroys a stopped container's exit status">. The value is
that engine's sentinel for "no status", not an exit code.
This endpoint is also the reason the error check on L</stats> matches
C<cause>, C<message> and C<response> case-sensitively: a I<successful> wait
is a 2xx body with a top-level C<Error> key in it, and a rule matching
C<error> case-insensitively would turn every one of them into a failure.
Options:
=over
=item * C<condition> - What to wait for: C<not-running> (the engine's own
default), C<next-exit> or C<removed>. Sent only when given
=back
=head2 pause
$containers->pause($id);
Pause all processes in a container.
Reports 1/0 like L</start>, but pausing an already-paused container is an
error rather than a 304: measured against Podman 5.4.2 (API 1.41) it answers
C<500> with C<< "..." is already paused: container state improper >>, which
croaks. The Docker Engine API documents no 304 for this endpoint either. So
this method returns 1 or croaks in practice.
=head2 unpause
$containers->unpause($id);
Unpause all processes in a container. Reports 1/0 like L</start>; as with
L</pause>, the no-op is an error and not a 304 -- Podman 5.4.2 answers
unpausing a running container with C<500>.
=head2 rename
$containers->rename($id, 'new-name');
Rename a container.
=head2 update
$containers->update($id, Memory => 314572800);
Update container resource limits and configuration.
The boolean flags (C<Init>, C<OomKillDisable>) may be given as a Perl C<1>/C<0>
or as a JSON boolean; either goes out as a real JSON C<true>/C<false>, which
the engine's body type-check requires.
=head2 get_archive
use Path::Tiny;
my $tar = $containers->get_archive($id, path => '/etc/hostname');
path('hostname.tar')->spew_raw($tar);
# and what the path was, without a second request
my %stat;
my $tar = $containers->get_archive($id, path => '/var/log', stat => \%stat);
say $stat{name};
Read a path out of a container as a tar archive -- the outbound half of
C<docker cp>. Returns the raw archive bytes, never decoded and never modified.
A file comes back as a one-member archive named after its basename; a
directory comes back as the directory and everything under it, with paths
relative to its parent. The whole archive is buffered in memory.
Options:
=over
=item * C<path> - Path inside the container to read. Required
=item * C<stat> - HashRef the C<X-Docker-Container-Path-Stat> header is
decoded into. The engine sends it on this response as well as on the HEAD
one, so asking for it here saves the extra round trip L</stat_archive> would
cost. Emptied when the engine sent no such header. See L</stat_archive> for
the keys
=back
=head2 put_archive
use Path::Tiny;
$containers->put_archive($id, path('payload.tar')->slurp_raw,
path => '/opt/app');
Write a tar archive into a path inside the container -- the inbound half of
C<docker cp>. The archive is the request body; pass it as raw bytes or as a
scalar reference to them, the way L<API::Docker::API::Images/load> takes its
( run in 1.063 second using v1.01-cache-2.11-cpan-b301d465b3d )