Message ID | 87muhws4hd.fsf_-_@sdf.lonestar.org |
---|---|
State | Accepted |
Headers | show |
Series | Add 'guix deploy'. | expand |
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. :)
Hi, Christopher Lemmer Webber <cwebber@dustycloud.org> skribis: > From my perspective, this is ready to merge. Which means that we need > to merge Ludo's remote-eval too. Yes, sorry for the delay on this. I started wondering about details of the ‘lower-gexp’ API; I’ll try to get to it today… Thanks, Ludo’.
On Tue, Jul 2, 2019 at 1:58 PM Jakob L. Kreuze <zerodaysfordays@sdf.lonestar.org> wrote: > > * doc/guix.texi: Add section "Invoking guix deploy". Looks good to me. Congratulations in advance for getting 'guix deploy' to master! - Dave
zerodaysfordays@sdf.lonestar.org (Jakob L. Kreuze) skribis: > * doc/guix.texi: Add section "Invoking guix deploy". Yay! You can add a copyright line for you at the top of guix.texi. > +@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''. Perhaps add something like: @quotation Note The functionality described in this section is still under development and is subject to change. Get in touch with us on @email{guix-devel@@gnu.org}! @end quotation That way, if we make a Guix release before this is all stabilized, we make sure people have appropriate expectations. :-) > +complex deployment may involve, for example, starting virtual machines through > +a VPS provider. In such a case, a different @var{environment} type would be ^^^ I would write “Virtual Private Server (VPS)”. I hope the nitpicking level is acceptable, let me know. I’m really excited to see this land in master! Ludo’.
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