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= \
|
content_files= \
|
||||||
overview.xml \
|
overview.xml \
|
||||||
repo.xml \
|
repo.xml \
|
||||||
|
deployment.xml \
|
||||||
$(NULL)
|
$(NULL)
|
||||||
|
|
||||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
# 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="overview.xml"/>
|
||||||
<xi:include href="repo.xml"/>
|
<xi:include href="repo.xml"/>
|
||||||
|
<xi:include href="deployment.xml"/>
|
||||||
|
|
||||||
<chapter xml:id="reference">
|
<chapter xml:id="reference">
|
||||||
<title>API Reference</title>
|
<title>API Reference</title>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue