From: zerodaysfordays@sdf.lonestar.org (Jakob L. Kreuze)
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: 36404@debbugs.gnu.org
Subject: [bug#36404] [PATCH v5 4/4] doc: Add section for 'guix deploy'.
Date: Fri, 05 Jul 2019 14:57:39 -0400 [thread overview]
Message-ID: <87v9wgfgws.fsf_-_@sdf.lonestar.org> (raw)
In-Reply-To: <87zhlsfgzc.fsf_-_@sdf.lonestar.org> (Jakob L. Kreuze's message of "Fri, 05 Jul 2019 14:56:07 -0400")
[-- Attachment #1: Type: text/plain, Size: 6719 bytes --]
* doc/guix.texi: Add section "Invoking guix deploy".
---
doc/guix.texi | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 114 insertions(+)
diff --git a/doc/guix.texi b/doc/guix.texi
index 9dc1d2a9c..8d9b7c575 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -65,6 +65,7 @@ Copyright @copyright{} 2018 Alex Vong@*
Copyright @copyright{} 2019 Josh Holland@*
Copyright @copyright{} 2019 Diego Nicola Barbato@*
Copyright @copyright{} 2019 Ivan Petkov@*
+Copyright @copyright{} 2019 Jakob L. Kreuze@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -81,6 +82,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 +271,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 +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 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 +25339,116 @@ 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''.
+
+@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
+
+@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 Virtual Private Server (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
--
2.22.0
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]
next prev parent reply other threads:[~2019-07-05 18:58 UTC|newest]
Thread overview: 84+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-06-27 18:35 [bug#36404] [PATCH 0/6] Add 'guix deploy' Jakob L. Kreuze
2019-06-27 18:38 ` [bug#36404] [PATCH 1/6] Take another stab at this whole guix deploy thing Jakob L. Kreuze
2019-06-27 18:39 ` [bug#36404] [PATCH 2/6] ssh: Add 'identity' keyword to 'open-ssh-session' Jakob L. Kreuze
2019-06-27 18:40 ` [bug#36404] [PATCH 3/6] gnu: Add machine type for deployment specifications Jakob L. Kreuze
2019-06-27 18:40 ` [bug#36404] [PATCH 4/6] Export the (gnu machine) interface Jakob L. Kreuze
2019-06-27 18:41 ` [bug#36404] [PATCH 5/6] Add 'guix deploy' Jakob L. Kreuze
2019-06-27 18:42 ` [bug#36404] [PATCH 6/6] doc: Add section for " Jakob L. Kreuze
2019-06-29 21:43 ` Christopher Lemmer Webber
2019-06-30 0:35 ` Jakob L. Kreuze
2019-06-29 21:38 ` [bug#36404] [PATCH 5/6] Add " Christopher Lemmer Webber
2019-06-29 21:36 ` [bug#36404] [PATCH 4/6] Export the (gnu machine) interface Christopher Lemmer Webber
2019-06-29 22:04 ` Ricardo Wurmus
2019-06-30 0:41 ` Jakob L. Kreuze
2019-06-27 20:05 ` [bug#36404] [PATCH 0/6] Add 'guix deploy' Thompson, David
2019-06-28 13:34 ` [bug#36404] [PATCH 0/5] " Jakob L. Kreuze
2019-06-28 13:35 ` [bug#36404] [PATCH 1/5] ssh: Add 'identity' keyword to 'open-ssh-session' Jakob L. Kreuze
2019-06-28 13:35 ` [bug#36404] [PATCH 2/5] gnu: Add machine type for deployment specifications Jakob L. Kreuze
2019-06-28 13:36 ` [bug#36404] [PATCH 3/5] Add 'guix deploy' Jakob L. Kreuze
2019-06-28 13:37 ` [bug#36404] [PATCH 4/5] Export the (gnu machine) interface Jakob L. Kreuze
2019-06-28 13:37 ` [bug#36404] [PATCH 5/5] doc: Add section for 'guix deploy' Jakob L. Kreuze
2019-06-29 21:36 ` [bug#36404] [PATCH 2/5] gnu: Add machine type for deployment specifications Christopher Lemmer Webber
2019-06-30 0:30 ` Jakob L. Kreuze
2019-06-30 4:58 ` Carlo Zancanaro
2019-06-30 12:34 ` Christopher Lemmer Webber
2019-07-01 23:51 ` Jakob L. Kreuze
2019-07-04 12:48 ` Christopher Lemmer Webber
2019-07-04 16:05 ` Jakob L. Kreuze
2019-06-30 12:28 ` Christopher Lemmer Webber
2019-07-02 0:03 ` Jakob L. Kreuze
2019-06-29 14:42 ` [bug#36404] [PATCH 1/5] ssh: Add 'identity' keyword to 'open-ssh-session' Christopher Lemmer Webber
2019-06-29 23:45 ` Jakob L. Kreuze
2019-06-29 14:37 ` [bug#36404] [PATCH 0/6] Add 'guix deploy' Christopher Lemmer Webber
2019-06-29 23:42 ` Jakob L. Kreuze
2019-07-01 12:50 ` Ludovic Courtès
2019-07-01 10:09 ` Ricardo Wurmus
2019-07-01 12:53 ` Ludovic Courtès
2019-07-02 0:10 ` Jakob L. Kreuze
2019-07-02 22:14 ` Jakob L. Kreuze
2019-07-04 16:48 ` Jakob L. Kreuze
2019-07-05 8:00 ` Ludovic Courtès
2019-07-05 23:45 ` [bug#36404] [PATCH 0/3] Refactor out common behavior for system reconfiguration Jakob L. Kreuze
2019-07-05 23:46 ` [bug#36404] [PATCH 1/3] guix system: Add 'reconfigure' module Jakob L. Kreuze
2019-07-05 23:47 ` [bug#36404] [PATCH 2/3] machine: Reimplement 'managed-host-environment-type' deployment Jakob L. Kreuze
2019-07-05 23:48 ` [bug#36404] [PATCH 3/3] guix system: Reimplement 'reconfigure' Jakob L. Kreuze
2019-07-06 22:20 ` Ludovic Courtès
2019-07-06 22:13 ` [bug#36404] [PATCH 2/3] machine: Reimplement 'managed-host-environment-type' deployment Ludovic Courtès
2019-07-07 7:13 ` Christopher Lemmer Webber
2019-07-07 13:05 ` Ludovic Courtès
2019-07-06 22:11 ` [bug#36404] [PATCH 1/3] guix system: Add 'reconfigure' module Ludovic Courtès
2019-07-06 22:02 ` [bug#36404] [PATCH 0/3] Refactor out common behavior for system reconfiguration Ludovic Courtès
2019-07-07 7:02 ` Christopher Lemmer Webber
2019-07-07 13:06 ` Ludovic Courtès
2019-07-08 19:22 ` Jakob L. Kreuze
2019-07-02 0:14 ` [bug#36404] [PATCH 0/4] Add 'guix deploy' Jakob L. Kreuze
2019-07-02 0:16 ` [bug#36404] [PATCH 1/4] ssh: Add 'identity' keyword to 'open-ssh-session' Jakob L. Kreuze
2019-07-02 0:17 ` [bug#36404] [PATCH 2/4] gnu: Add machine type for deployment specifications Jakob L. Kreuze
2019-07-02 0:17 ` [bug#36404] [PATCH 3/4] Add 'guix deploy' Jakob L. Kreuze
2019-07-02 0:18 ` [bug#36404] [PATCH 4/4] doc: Add section for " Jakob L. Kreuze
[not found] ` <875zoldqah.fsf@kyleam.com>
[not found] ` <87muhwtmfp.fsf@sdf.lonestar.org>
[not found] ` <871rz874l2.fsf@kyleam.com>
[not found] ` <877e90tj7l.fsf_-_@sdf.lonestar.org>
2019-07-02 17:56 ` [bug#36404] [PATCH v4 1/4] ssh: Add 'identity' keyword to 'open-ssh-session' Jakob L. Kreuze
2019-07-02 17:56 ` [bug#36404] [PATCH v4 2/4] gnu: Add machine type for deployment specifications Jakob L. Kreuze
2019-07-02 17:57 ` [bug#36404] [PATCH v4 3/4] Add 'guix deploy' Jakob L. Kreuze
2019-07-02 17:58 ` [bug#36404] [PATCH v4 4/4] doc: Add section for " Jakob L. Kreuze
2019-07-03 23:07 ` Christopher Lemmer Webber
2019-07-04 9:20 ` Ludovic Courtès
2019-07-05 1:39 ` Thompson, David
2019-07-05 8:29 ` Ludovic Courtès
2019-07-05 1:35 ` [bug#36404] [PATCH v4 3/4] Add " Thompson, David
2019-07-05 8:17 ` Ludovic Courtès
2019-07-04 9:19 ` [bug#36404] [PATCH v4 2/4] gnu: Add machine type for deployment specifications Ludovic Courtès
2019-07-04 15:59 ` Jakob L. Kreuze
2019-07-05 1:32 ` Thompson, David
2019-07-05 8:10 ` Ludovic Courtès
2019-07-05 8:24 ` Ludovic Courtès
2019-07-05 18:53 ` [bug#36404] [PATCH v5 0/4] Add 'guix deploy' Jakob L. Kreuze
2019-07-05 18:54 ` [bug#36404] [PATCH v5 1/4] ssh: Add 'identity' keyword to 'open-ssh-session' Jakob L. Kreuze
2019-07-05 18:55 ` [bug#36404] [PATCH v5 2/4] gnu: Add machine type for deployment specifications Jakob L. Kreuze
2019-07-05 18:56 ` [bug#36404] [PATCH v5 3/4] Add 'guix deploy' Jakob L. Kreuze
2019-07-05 18:57 ` Jakob L. Kreuze [this message]
2019-07-06 6:14 ` bug#36404: [PATCH v5 4/4] doc: Add section for " Christopher Lemmer Webber
2019-07-05 23:25 ` [bug#36404] " Jakob L. Kreuze
2019-07-06 21:50 ` Ludovic Courtès
2019-07-05 1:23 ` [bug#36404] [PATCH v4 1/4] ssh: Add 'identity' keyword to 'open-ssh-session' Thompson, David
2019-07-01 12:48 ` [bug#36404] [PATCH 0/6] Add 'guix deploy' Ludovic Courtès
2019-07-05 10:32 ` [bug#36404] [PATCH v4 2/4] gnu: Add machine type for deployment specifications Christopher Lemmer Webber
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87v9wgfgws.fsf_-_@sdf.lonestar.org \
--to=zerodaysfordays@sdf.lonestar.org \
--cc=36404@debbugs.gnu.org \
--cc=ludo@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).