From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:470:142:3::10]:57358) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hioN5-0001L4-Ft for guix-patches@gnu.org; Wed, 03 Jul 2019 19:09:04 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hioN4-0003Oa-3V for guix-patches@gnu.org; Wed, 03 Jul 2019 19:09:03 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:41350) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hioN3-0003OS-Vs for guix-patches@gnu.org; Wed, 03 Jul 2019 19:09:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hioN3-0004pN-OJ for guix-patches@gnu.org; Wed, 03 Jul 2019 19:09:01 -0400 Subject: [bug#36404] [PATCH v4 4/4] doc: Add section for 'guix deploy'. Resent-Message-ID: References: <87o92ianbj.fsf@sdf.lonestar.org> <87o92glap5.fsf@dustycloud.org> <878sthoqzi.fsf@gnu.org> <87imsl9tsx.fsf_-_@sdf.lonestar.org> <87ef399tpu.fsf_-_@sdf.lonestar.org> <87a7dx9tog.fsf_-_@sdf.lonestar.org> <875zol9tn2.fsf_-_@sdf.lonestar.org> <871rz99tl9.fsf_-_@sdf.lonestar.org> <875zoldqah.fsf@kyleam.com> <87muhwtmfp.fsf@sdf.lonestar.org> <871rz874l2.fsf@kyleam.com> <877e90tj7l.fsf_-_@sdf.lonestar.org> <8736jotj5v.fsf_-_@sdf.lonestar.org> <87y31gs4k5.fsf_-_@sdf.lonestar.org> <87tvc4s4iv.fsf_-_@sdf.lonestar.org> <87muhws4hd.fsf_-_@sdf.lonestar.org> From: Christopher Lemmer Webber In-reply-to: <87muhws4hd.fsf_-_@sdf.lonestar.org> Date: Wed, 03 Jul 2019 19:07:51 -0400 Message-ID: <87ftnmn2d4.fsf@dustycloud.org> MIME-Version: 1.0 Content-Type: text/plain List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: "Jakob L. Kreuze" Cc: 36404@debbugs.gnu.org Jakob L. Kreuze writes: > * doc/guix.texi: Add section "Invoking guix deploy". > --- > doc/guix.texi | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 107 insertions(+) > > diff --git a/doc/guix.texi b/doc/guix.texi > index 9dc1d2a9c..0827a2bde 100644 > --- a/doc/guix.texi > +++ b/doc/guix.texi > @@ -81,6 +81,7 @@ Documentation License''. > * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space. > * guix pull: (guix)Invoking guix pull. Update the list of available packages. > * guix system: (guix)Invoking guix system. Manage the operating system configuration. > +* guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts. > @end direntry > > @dircategory Software development > @@ -269,6 +270,7 @@ System Configuration > * Initial RAM Disk:: Linux-Libre bootstrapping. > * Bootloader Configuration:: Configuring the boot loader. > * Invoking guix system:: Instantiating a system configuration. > +* Invoking guix deploy:: Deploying a system configuration to a remote host. > * Running Guix in a VM:: How to run Guix System in a virtual machine. > * Defining Services:: Adding new service definitions. > > @@ -10302,6 +10304,7 @@ instance to support new system services. > * Initial RAM Disk:: Linux-Libre bootstrapping. > * Bootloader Configuration:: Configuring the boot loader. > * Invoking guix system:: Instantiating a system configuration. > +* Invoking guix deploy:: Deploying a system configuration to a remote host. > * Running Guix in a VM:: How to run Guix System in a virtual machine. > * Defining Services:: Adding new service definitions. > @end menu > @@ -25335,6 +25338,110 @@ example graph. > > @end table > > +@node Invoking guix deploy > +@section Invoking @code{guix deploy} > + > +We've already seen @code{operating-system} declarations used to manage a > +machine's configuration locally. Suppose you need to configure multiple > +machines, though---perhaps you're managing a service on the web that's > +comprised of several servers. @command{guix deploy} enables you to use those > +same @code{operating-system} declarations to manage multiple remote hosts at > +once as a logical ``deployment''. > + > +@example > +guix deploy @var{file} > +@end example > + > +Such an invocation will deploy the machines that the code within @var{file} > +evaluates to. As an example, @var{file} might contain a definition like this: > + > +@example > +;; This is a Guix deployment of a "bare bones" setup, with > +;; no X11 display server, to a machine with an SSH daemon > +;; listening on localhost:2222. A configuration such as this > +;; may be appropriate for virtual machine with ports > +;; forwarded to the host's loopback interface. > + > +(use-service-modules networking ssh) > +(use-package-modules bootloaders) > + > +(define %system > + (operating-system > + (host-name "gnu-deployed") > + (timezone "Etc/UTC") > + (bootloader (bootloader-configuration > + (bootloader grub-bootloader) > + (target "/dev/vda") > + (terminal-outputs '(console)))) > + (file-systems (cons (file-system > + (mount-point "/") > + (device "/dev/vda1") > + (type "ext4")) > + %base-file-systems)) > + (services > + (append (list (service dhcp-client-service-type) > + (service openssh-service-type > + (openssh-configuration > + (permit-root-login #t) > + (allow-empty-passwords? #t)))) > + %base-services)))) > + > +(list (machine > + (system %system) > + (environment managed-host-environment-type) > + (configuration (machine-ssh-configuration > + (host-name "localhost") > + (identity "./id_rsa") > + (port 2222))))) > +@end example > + > +The file should evaluate to a list of @var{machine} objects. This example, > +upon being deployed, will create a new generation on the remote system > +realizing the @code{operating-system} declaration @var{%system}. > +@var{environment} and @var{configuration} specify how the machine should be > +provisioned---that is, how the computing resources should be created and > +managed. The above example does not create any resources, as a > +@code{'managed-host} is a machine that is already running the Guix system and > +available over the network. This is a particularly simple case; a more > +complex deployment may involve, for example, starting virtual machines through > +a VPS provider. In such a case, a different @var{environment} type would be > +used. > + > +@deftp {Data Type} machine > +This is the data type representing a single machine in a heterogeneous Guix > +deployment. > + > +@table @asis > +@item @code{system} > +The object of the operating system configuration to deploy. > + > +@item @code{environment} > +An @code{environment-type} describing how the machine should be provisioned. > +At the moment, the only supported value is > +@code{managed-host-environment-type}. > + > +@item @code{configuration} (default: @code{#f}) > +An object describing the configuration for the machine's @code{environment}. > +If the @code{environment} has a default configuration, @code{#f} maybe used. > +If @code{#f} is used for an environment with no default configuration, > +however, an error will be thrown. > +@end table > +@end deftp > + > +@deftp {Data Type} machine-ssh-configuration > +This is the data type representing the SSH client parameters for a machine > +with an @code{environment} of @code{managed-host-environment-type}. > + > +@table @asis > +@item @code{host-name} > +@item @code{port} (default: @code{22}) > +@item @code{user} (default: @code{"root"}) > +@item @code{identity} (default: @code{#f}) > +If specified, the path to the SSH private key to use to authenticate with the > +remote host. > +@end table > +@end deftp > + > @node Running Guix in a VM > @section Running Guix in a Virtual Machine All looks good to me. >From my perspective, this is ready to merge. Which means that we need to merge Ludo's remote-eval too. Of course others may catch things, but I'd say let's not take too long... we should get this in and let people start playing with it. :)