[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug#36404] [PATCH 6/6] doc: Add section for 'guix deploy'.
From: |
Jakob L. Kreuze |
Subject: |
[bug#36404] [PATCH 6/6] doc: Add section for 'guix deploy'. |
Date: |
Thu, 27 Jun 2019 14:42:20 -0400 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.2 (gnu/linux) |
2019-06-26 Jakob L. Kreuze <address@hidden>
doc/guix.texi: Add section "Invoking guix deploy".
---
doc/guix.texi | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 103 insertions(+)
diff --git a/doc/guix.texi b/doc/guix.texi
index f0d148ace0..948767d8c8 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.
@@ -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 remote
host.
* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
@end menu
@@ -25399,6 +25402,106 @@ example graph.
@end table
+@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 remote
+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 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-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 system
+realizing the operating-system configuration @var{%system}. @var{environment}
+and @var{configuration} specify how the machine should be provisioned--that is,
+deployment and management of computing resources. The above example does not
+provision any resources -- a @code{'managed-host} is a machine that is already
+up and running the Guix system. A more complex deployment may involve
+i.e. starting virtual machines through a VPS provider, however, in which case 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, 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 connecting 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
--
2.22.0
- [bug#36404] [PATCH 0/6] Add 'guix deploy'., Jakob L. Kreuze, 2019/06/27
- [bug#36404] [PATCH 1/6] Take another stab at this whole guix deploy thing., Jakob L. Kreuze, 2019/06/27
- [bug#36404] [PATCH 2/6] ssh: Add 'identity' keyword to 'open-ssh-session'., Jakob L. Kreuze, 2019/06/27
- [bug#36404] [PATCH 3/6] gnu: Add machine type for deployment specifications., Jakob L. Kreuze, 2019/06/27
- [bug#36404] [PATCH 4/6] Export the (gnu machine) interface., Jakob L. Kreuze, 2019/06/27
- [bug#36404] [PATCH 5/6] Add 'guix deploy'., Jakob L. Kreuze, 2019/06/27
- [bug#36404] [PATCH 6/6] doc: Add section for 'guix deploy'.,
Jakob L. Kreuze <=
- [bug#36404] [PATCH 6/6] doc: Add section for 'guix deploy'., Christopher Lemmer Webber, 2019/06/29
- [bug#36404] [PATCH 6/6] doc: Add section for 'guix deploy'., Jakob L. Kreuze, 2019/06/29
- [bug#36404] [PATCH 5/6] Add 'guix deploy'., Christopher Lemmer Webber, 2019/06/29
- [bug#36404] [PATCH 4/6] Export the (gnu machine) interface., Christopher Lemmer Webber, 2019/06/29
- [bug#36404] [PATCH 4/6] Export the (gnu machine) interface., Ricardo Wurmus, 2019/06/29
- [bug#36404] [PATCH 4/6] Export the (gnu machine) interface., Jakob L. Kreuze, 2019/06/29
[bug#36404] [PATCH 0/6] Add 'guix deploy'., Thompson, David, 2019/06/27