From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:470:142:3::10]:58169) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hgr6o-0005kF-RL for guix-patches@gnu.org; Fri, 28 Jun 2019 09:40:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hgr6k-0004tK-Py for guix-patches@gnu.org; Fri, 28 Jun 2019 09:40:08 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:55294) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hgr6f-0004im-UZ for guix-patches@gnu.org; Fri, 28 Jun 2019 09:40:04 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hgr6f-00037j-Qk for guix-patches@gnu.org; Fri, 28 Jun 2019 09:40:01 -0400 Subject: [bug#36404] [PATCH 5/5] doc: Add section for 'guix deploy'. Resent-Message-ID: From: zerodaysfordays@sdf.lonestar.org (Jakob L. Kreuze) References: <87o92ianbj.fsf@sdf.lonestar.org> <87imspj0ks.fsf_-_@sdf.lonestar.org> <87ef3dj0j9.fsf_-_@sdf.lonestar.org> <87a7e1j0hy.fsf_-_@sdf.lonestar.org> <875zopj0gs.fsf_-_@sdf.lonestar.org> <871rzdj0fu.fsf_-_@sdf.lonestar.org> Date: Fri, 28 Jun 2019 09:37:49 -0400 In-Reply-To: <871rzdj0fu.fsf_-_@sdf.lonestar.org> (Jakob L. Kreuze's message of "Fri, 28 Jun 2019 09:37:09 -0400") Message-ID: <87woh5hlua.fsf_-_@sdf.lonestar.org> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" 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: "Thompson, David" Cc: 36404@debbugs.gnu.org --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable * doc/guix.texi: Add section "Invoking guix deploy". =2D-- doc/guix.texi | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index f0d148ace0..948767d8c8 100644 =2D-- 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 conf= igurations for remote hosts. @end direntry =20 @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 remo= te host. * Running Guix in a VM:: How to run Guix System in a virtual machin= e. * Defining Services:: Adding new service definitions. =20 @@ -10303,6 +10305,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 remo= te host. * Running Guix in a VM:: How to run Guix System in a virtual machin= e. * Defining Services:: Adding new service definitions. @end menu @@ -25399,6 +25402,106 @@ example graph. =20 @end table =20 +@node Invoking guix deploy +@section Invoking @code{guix deploy} + +In addition to managing a machine's configuration locally through operating +system declarations, Guix also provides the ability to managing multiple r= emote +hosts as a logical ``deployment''. This is done using @command{guix deploy= }. + +@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 th= is: + +@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-modules (gnu) (guix)) +(use-machine-modules ssh) +(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) + (configuration (machine-ssh-configuration + (host-name "localhost") + (identity "./id_rsa") + (port 2222))))) +@end example + +The file should evaluate to a list of machines, rather than just one. This +example, upon being deployed, will create a new generation on the remote s= ystem +realizing the operating-system configuration @var{%system}. @var{environme= nt} +and @var{configuration} specify how the machine should be provisioned--tha= t is, +deployment and management of computing resources. The above example does n= ot +provision any resources -- a @code{'managed-host} is a machine that is alr= eady +up and running the Guix system. A more complex deployment may involve +i.e. starting virtual machines through a VPS provider, however, in which c= ase a +different @var{environment} types 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} +A symbol describing how the machine should be provisioned. At the moment, = only +the only supported value is @code{'managed-host}. + +@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} can be used.= If +@code{#f} is used for an environment with no default configuration, howeve= r, 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 connectin= g to a +@code{'managed-host}. + +@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 =20 =2D-=20 2.22.0 --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEa1VJLOiXAjQ2BGSm9Qb9Fp2P2VoFAl0WGC0ACgkQ9Qb9Fp2P 2VpbYQ//foEWOlRxR81k1VlkerL++wel/Dh1JOJxtCso874rEpdmkvXAhzBGQs5p vXB56n6bfVAbzc875EUSBc8CT5q15l/u/sf5AoqmEy92/06txTT3MN5Y9kIBqOl6 46U7Y/mmezg84BGu1fQUnfxfQBZBH69BObtGSxbuCZBl60XScmjpZKYqEq8d+/bi wncKIEHVQTmKP5CEcc7K8cShF1m3TEHcD2dvHckPg3iC6/k8QexbjZzDMD6tGv+i PCTiWtClMqn7oEOVmM4OAFB8o/AHOFVWBy20H9WlbtniCeGd9dvCjWkiPV+GV4N5 1cGf2P1v5OBUEO3ONuhgSDXHuHXKksowJ/FRaJDUBALQUzFYTvPNjwRzulbzotqa 3kNOVgMT0TtA+t5S0VJV0pxlqCXguuFkqUQRuPiyUL7cFKbyAWCbNH866Xk6QMbU 3zhU/CpKZ9ktj1pb2/wdMXUaOng6LBOgyfTXYSibeu6wdb16q/Wq478qJqTot0LD dt/tjxSGDkIvv5XGkTa4Lo2+IjA+WMCAN6L2auqtz3MsrfyWfjefLzXUNRjRNiA2 y7uhCGBFoKsZ+22YNwjHqSrRMJlJwvHO++yK3/8xnLuTDfsQETgUCGPc2xMK+LPZ G2n1fW98fGH1YxUKc5PpDm6YRz7Rt5c30kakEzyKDgSu/FxvnUE= =LjvK -----END PGP SIGNATURE----- --=-=-=--