view release on metacpan or  search on metacpan

lib/Net/Async/WebService/lxd.pm  view on Meta::CPAN

    map { @{ $_->{tags} } } values %$META;
    my @tags = keys %tags;

    use File::Slurp;

    my $pod = q{
=head1 NAME

Net::Async::WebService::lxd - REST client (asynchronous) for lxd Linux containers

=head1 SYNOPSIS

   use IO::Async::Loop;
   my $loop = IO::Async::Loop->new;

   use Net::Async::WebService::lxd;
   my $lxd = Net::Async::WebService::lxd->new( loop            => $loop,
					       endpoint        => 'https://192.168.0.50:8443',
					       SSL_cert_file   => "t/client.crt",
					       SSL_key_file    => "t/client.key",
					       SSL_fingerprint => 'sha1$92:DD:63:F8:99:C4:5F:82:59:52:82:A9:09:C8:57:F0:67:56:B0:1B',
                                               );
   $lxd->create_instance(
	    body => {
		architecture => 'x86_64',
		profiles     => [ 'default'  ],
		name         => 'test1',
		source       => { type        => 'image',
				  fingerprint => '6dc6aa7c8c00' },  # image already exists in image store
		config       => {},
	    } )->get;                                               # wait for it
   # container is still stopped
   $lxd->instance_state( name => 'test1',
            body => {
                action   => "start",
		force    => JSON::false,
		stateful => JSON::false,
		timeout  => 30,
	    } )->get;                                               # wait for it


=head1 INTERFACE

=head2 Constructor

The constructor returns a handle to one LXD server. It's address is specified via an B<endpoint>
parameter, be it of an HTTPS or of a UNIX socket kind.

If you are working with a non-default LXD project in mind, then you should also provide that
project's name with the B<project> parameter. Background operation polling will make use of
that. Note, that when invoking any of the methods here, you will still have to specify that project,
unless it is the C<default> one, of course.

As we are operating under an L<IO::Async> regime here, the handle also needs a B<loop> parameter to
the central event loop. The handle will also regularily poll autonomously the server which
operations are still running or have completed. The optional parameter B<polling_time> controls how
often that will occur; it will default to 1 sec, if not provided.

As LXC can be accessed remotely only via HTTPS, TLS (SSL) parameters must be provided. These will be
forwarded directly to
L<IO::Socket::SSL|https://metacpan.org/pod/IO::Socket::SSL#Description-Of-Methods>. But, specifically,
one should consider to provide:

=over

=item * B<client certificate>, via a proper subset of C<SSL_cert_file>, C<SSL_key_file>, C<SSL_cert> and C<SSL_key>.
(Look at the L</HINTS> section to generate such a certificate for LXD.)

=item * B<server fingerprint>, via C<SSL_fingerprint>
(Look at the L</HINTS> section how to figure this out.)

=back

=head2 Methods

All methods below are automatically generated from the L<LXD REST API Spec|https://raw.githubusercontent.com/lxc/lxd/master/doc/rest-api.yaml>.
They should work with API version 1.0.


Let's dissect method invocations with this example:

   my $f = $lxd->instance_state( name => 'test1' );
   my $r = $f->get;

=over

=item *

All invocations return a L<Future>. Thus they can be combined, sequenced, run in "parallel", etc. If
you need to wait for a definite result, then you will block the flow with C<-E<gt>get>.

Polling is done behind the scenes and will watch for all operations which either succeeded or
failed. Those will mark the associated future as C<done> or C<failed>. Normally, you will never need
to use the methods for 'Operations' yourself; they are still offered as fallback.

=item *

The result of each fully completed invocation is either

=over

=item *

the string C<success>, or

=item *

a Perl HASH ref which reflects the JSON data sent from the LXD server. Note, that Booleans have to
be treated special, by using C<JSON::false> and C<JSON::true>. Otherwise, they follow B<exactly> the
structure in the specification.

=item *

or a HASH ref with keys C<stdin> and C<stdout> if this is a result of the C<execute_in_instance>
method.

=back

=item *

If an operation failed, then the associated future will be failed, together with the reason of the

lib/Net/Async/WebService/lxd.pm  view on Meta::CPAN

Well, I'm not a big fan of objects.


=head1 EXAMPLES

I encourage you to look at the C<02_instances.t> test suite. It will show a complete life cycle for
containers.

=head1 SEE ALSO

=over

=item * L<Linux::LXC>

uses actually the existing lxc client to get the information

=item * L<https://github.com/jipipayo/Linux-REST-LXD>

pretty old, never persued

=back


=head1 HINTS

=over

=item * How to generate an SSL client certificate for LXD

First, I found one client certificate (plus the key) in my installation at:

   /root/snap/lxd/common/config/

Alternatively, L<you can run your own small CA, generate a .crt and .key for a client, and then
add it to lxd to trust it|https://serverfault.com/questions/882880/authenticate-to-lxd-rest-api-over-network-certificate-auth-keeps-failing>.

More on this topic is L<here|https://linuxcontainers.org/lxd/docs/master/authentication/>

=item * How to find the SSL fingerprint for an LXD server

With recent versions of LXD this is fairly easy:

   $ lxc info|grep fingerprint

It is a SHA265 hash, so you will have to prefix it with C<sha256$> (no blanks) when you pass it to C<SSL_fingerprint>.

Alternatively, you can try to find the server certificate and use C<openssl> to derive a fingerprint of your choice.

=back

=head1 ISSUES

Open issues are probably best put onto L<Github|https://github.com/drrrho/net-async-webservice-lxd>

=head1 AUTHOR

Robert Barta, C<< <rho at devc.at> >>

=head1 CREDITS

L<IO::Async>, L<Net::Async::HTTP>, L<IO::Socket::SSL> and friends are amazing.

=head1 LICENSE AND COPYRIGHT

Copyright 2022 Robert Barta.

}
.
read_file("LICENSE")
;
print $pod;
}


1; # End of Net::Async::WebService::lxd

__DATA__
definitions:
  Certificate:
    description: Certificate represents a LXD certificate
    properties:
      certificate:
        description: The certificate itself, as PEM encoded X509
        example: X509 PEM certificate
        type: string
        x-go-name: Certificate
      fingerprint:
        description: SHA256 fingerprint of the certificate
        example: fd200419b271f1dc2a5591b693cc5774b7f234e1ff8c6b78ad703b6888fe2b69
        readOnly: true
        type: string
        x-go-name: Fingerprint
      name:
        description: Name associated with the certificate
        example: castiana
        type: string
        x-go-name: Name
      projects:
        description: List of allowed projects (applies when restricted)
        example:
        - default
        - foo
        - bar
        items:
          type: string
        type: array
        x-go-name: Projects
      restricted:
        description: Whether to limit the certificate to listed projects
        example: true
        type: boolean
        x-go-name: Restricted
      type:
        description: Usage type for the certificate (only client currently)
        example: client
        type: string
        x-go-name: Type
    type: object
    x-go-package: github.com/lxc/lxd/shared/api
  CertificateAddToken:
    properties: