doc: Add a section on deployments
This commit is contained in:
Colin Walters
parent
695621db05
commit
d58d6a6ef2
|
|
@ -76,6 +76,7 @@ HTML_IMAGES=
|
|||
content_files= \
|
||||
overview.xml \
|
||||
repo.xml \
|
||||
deployment.xml \
|
||||
$(NULL)
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
|
|
|
|||
|
|
@ -0,0 +1,147 @@
|
|||
<?xml version="1.0"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||
<!ENTITY version SYSTEM "../version.xml">
|
||||
]>
|
||||
<part id="deployment">
|
||||
<title>Deployments</title>
|
||||
<chapter id="deployment-intro">
|
||||
<title>Overview</title>
|
||||
<para>
|
||||
Built on top of the OSTree versioning filesystem core is a layer
|
||||
that knows how to deploy, parallel install, and manage Unix-like
|
||||
operating systems (accessible via <command>ostree
|
||||
admin</command>). The core content of these operating systems
|
||||
are treated as read-only, but they transparently share storage.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A deployment is physically located at a path of the form
|
||||
<filename
|
||||
class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/deploy/<replaceable>checksum</replaceable></filename>.
|
||||
OSTree is designed to boot directly into exactly one deployment
|
||||
at a time; each deployment is intended to be a target for
|
||||
<literal>chroot()</literal> or equivalent.
|
||||
</para>
|
||||
|
||||
</chapter>
|
||||
|
||||
<chapter id="deployment-osname">
|
||||
<title>"osname": Group of deployments that share /var</title>
|
||||
<para>
|
||||
Each deployment is grouped in exactly one "osname". From
|
||||
above, you can see that an osname is physically represented in
|
||||
the <filename
|
||||
class='directory'>/ostree/deploy/<replaceable>osname</replaceable></filename>
|
||||
directory. For example, OSTree can allow parallel installing
|
||||
Debian in <filename
|
||||
class='directory'>/ostree/deploy/debian</filename> and Red Hat
|
||||
Enterprise Linux in <filename
|
||||
class='directory'>/ostree/deploy/rhel</filename> (subject to
|
||||
operating system support, present released versions of these
|
||||
operating systems may not support this).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Each osname has exactly one copy of the traditional Unix
|
||||
<filename class='directory'>/var</filename>, stored physically
|
||||
in <filename
|
||||
class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/var</filename>.
|
||||
OSTree provides support tools for <command>systemd</command>
|
||||
to create a Linux bind mount that ensures the booted
|
||||
deployment sees the shared copy of <filename
|
||||
class='directory'>/var</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
OSTree does not touch the contents of <filename
|
||||
class='directory'>/var</filename>. Operating system components
|
||||
such as daemon services are required to create any directories
|
||||
they require there at runtime (e.g. <filename
|
||||
class='directory'>/var/cache/<replaceable>daemonname</replaceable></filename>),
|
||||
and to manage upgrading data formats inside those directories.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="deployment-contents">
|
||||
<title>Contents of a deployment</title>
|
||||
<para>
|
||||
A deployment begins with a specific commit (represented as a
|
||||
SHA256 hash) in the OSTree repository in <filename
|
||||
class='directory'>/ostree/repo</filename>. This commit refers
|
||||
to a filesystem tree that represents the underlying basis of a
|
||||
deployment. For short, we will call this the "tree", to
|
||||
distinguish it from the concept of a deployment.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
First, the tree must include a kernel stored as <filename
|
||||
class='directory'>/boot/vmlinuz-<replaceable>checksum</replaceable></filename>.
|
||||
The checksum should be a SHA256 hash of the kernel contents;
|
||||
it must be pre-computed before storing the kernel in the
|
||||
repository. Optionally, the tree can contain an initramfs,
|
||||
stored as <filename
|
||||
class='directory'>/boot/initramfs-<replaceable>checksum</replaceable></filename>.
|
||||
If this exists, the checksum must include both the kernel and
|
||||
initramfs contents. OSTree will use this to determine which
|
||||
kernels are shared. The rationale for this is to avoid
|
||||
computing checksums on the client by default.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The deployment should not have a traditional UNIX <filename
|
||||
class='directory'>/etc</filename>; instead, it should include
|
||||
<filename class='directory'>/usr/etc</filename>. This is the
|
||||
"default configuration". When OSTree creates a deployment, it
|
||||
performs a 3-way merge using the <emphasis>old</emphasis>
|
||||
default configuration, the active system's <filename
|
||||
class='directory'>/etc</filename>, and the new default
|
||||
configuration. In the final filesystem tree for a deployment
|
||||
then, <filename class='directory'>/etc</filename> is a regular
|
||||
writable directory.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Besides the exceptions of <filename
|
||||
class='directory'>/var</filename> and <filename
|
||||
class='directory'>/etc</filename> then, the rest of the
|
||||
contents of the tree are checked out as hard links into the
|
||||
repository. It's strongly recommended that operating systems
|
||||
ship all of their content in <filename
|
||||
class='directory'>/usr</filename>, but this is not a hard
|
||||
requirement.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="managing-boot">
|
||||
<title>The system /boot</title>
|
||||
<para>
|
||||
While OSTree parallel installs deployments cleanly inside the
|
||||
<filename class='directory'>/ostree</filename> directory,
|
||||
ultimately it has to control the system's <filename
|
||||
class='directory'>/boot</filename> directory. The way this
|
||||
works is via the <ulink
|
||||
url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/">boot
|
||||
loader specification</ulink>, which is a standard for
|
||||
bootloader-independent drop-in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
When a tree is deployed, it will have a configuration file
|
||||
generated of the form <filename
|
||||
class='directory'>/boot/loader/entries/ostree-<replaceable>osname</replaceable>-<replaceable>checksum</replaceable>.<replaceable>serial</replaceable>.conf</filename>.
|
||||
This configuration file will include a special
|
||||
<literal>ostree=</literal> kernel argument that allows the
|
||||
initramfs to find (and <literal>chroot()</literal> into) the
|
||||
specified deployment.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
At present, not all bootloaders implement the BootLoaderSpec,
|
||||
so OSTree contains code for some of these to regenerate native
|
||||
config files (such as
|
||||
<filename>/boot/syslinux/syslinux.conf</filename> based on the
|
||||
entries.
|
||||
</para>
|
||||
|
||||
</chapter>
|
||||
</part>
|
||||
|
|
@ -13,6 +13,7 @@
|
|||
|
||||
<xi:include href="overview.xml"/>
|
||||
<xi:include href="repo.xml"/>
|
||||
<xi:include href="deployment.xml"/>
|
||||
|
||||
<chapter xml:id="reference">
|
||||
<title>API Reference</title>
|
||||
|
|
|
|||
Loading…
Reference in New Issue