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

NAME

API::Docker::Role::Entity::Secret - Secret operations, on the generated secret type

VERSION

version 0.004

SYNOPSIS

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

say $secret->id;
say $secret->spec->name;
say $secret->version_index;

my %spec = %{ $secret->spec->TO_JSON };
$spec{Labels} = { env => 'staging' };
$secret->update(%spec);

$secret->remove;

DESCRIPTION

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

There is no accessor for the value

A secret carries no payload on this API at all. The daemon hands the value to containers, never back over /secrets: neither list nor inspect returns a spec->data, so there is nothing here to decode. That is why this role has no decoded_data, where API::Docker::Role::Entity::Config does -- the difference is in what the engine sends, not in what the two choose to offer. In the GET /secrets response captured from Podman 5.4.2 (API 1.41) in t/fixtures/secrets_list.json, each object carries ID, CreatedAt, UpdatedAt, Spec and Version, and the Spec has Name, Driver and Labels but no Data key whatsoever. The swagger agrees: it documents SecretSpec.Data as used to create a secret and not returned by other endpoints.

$secret->spec->data therefore exists as an accessor -- the field is in the definition -- and reads undef on anything an engine sent back.

If you need to read a value back, a secret is the wrong storage -- put it in a config, see API::Docker::API::Configs.

The spec goes back as a whole

$secret->spec is an API::Docker::Type::SecretSpec object rather than the raw HashRef the hand-written entity kept, so the idiom for an update is %{ $secret->spec->TO_JSON }: TO_JSON renders the spec back into the daemon's own spelling, which is what "update" puts in the request body.

Why the whole spec and not the one key you changed: "update takes the current version, and it is mandatory" in API::Docker::API::Secrets.

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

version_index

my $index = $secret->version_index;

The ->index out of ->version, which is what the daemon wants as the version query parameter on an update. Returns nothing when the object carries no Version -- including the case where the daemon sent one the model could not use, which leaves the attribute unset and the raw value in ->unknown_fields->{Version}.

It is the version as of the moment this object was fetched, which is exactly the token's meaning: an update built on a stale entity is refused by the daemon rather than silently overwriting whatever changed in between.

inspect

my $fresh = $secret->inspect;

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

update

my %spec = %{ $secret->spec->TO_JSON };
$spec{Labels} = { env => 'staging' };
$secret->update(%spec);

Update the secret. Passes ->id and, by default, "version_index" to "update" in API::Docker::API::Secrets; everything else is the spec and becomes the request body.

The default is only a default. A version key in the arguments is used verbatim and removed before the spec goes out -- the spec's own fields are all capitalised (Name, Labels, Data, ...), so a lowercase version cannot collide with one:

$secret->update(version => $index, %spec);

Send the whole spec back with the one key edited; the Engine API accepts a change to Labels only and wants every other field unchanged. Podman does not implement this endpoint and answers 501.

remove

$secret->remove;

Remove the secret. The daemon answers 204 with no body, so this returns nothing.

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.