mixer: Adds bullet list in format bump; adds Example 3 for editors. (#659)

* Adds bullet list in format bump; adds Example 3 for editors.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

* Revise Editors example per reviewer feedback.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

* Revise to integrate form Ex. 4 into Ex. 2.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

* Integrates how to edit bundle editors in Ex. 2 and Ex. 3.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

* Respond to feedback.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
michael vincerra
2019-07-22 11:59:02 -07:00
committed by GitHub
parent 2cf769511e
commit 9cad7aa2dd
+97 -81
View File
@@ -3,10 +3,10 @@
mixer
#####
**mixer** is the tool used by the |CL-ATTR| team to generate official update content
and releases. The update content generated by mixer is then consumed by swupd on
a downstream client. The same mixer tool is available as part of |CL| to create
your own customized update content and releases.
**mixer** is the tool used by the |CL-ATTR| team to generate official update
content and releases. The update content generated by mixer is then consumed
by swupd on a downstream client. The same mixer tool is available as part of
|CL| to create your own customized update content and releases.
.. contents::
:local:
@@ -21,19 +21,12 @@ mixer uses the following sources as inputs to generate update content:
* Locally-defined bundles with their corresponding local RPM packages
* Locally-defined bundles with upstream RPM packages
Using the mixer tool, you select which set of content from these sources will be
part of your update. You can select content from each of these sources to make a
unique combination of functionality for your custom update content, known as a
**mix**.
Using the mixer tool, you select which set of content from these sources
will be part of your update. You can select content from each of these sources to make a unique combination of functionality for your custom update content, known as a **mix**.
The update content that mixer generates consists of various pieces of OS
content, update metadata, as well as a complete image. The OS content includes
all files in an update, as well as zero- and delta-packs for improved update
performance. The update metadata, stored as manifests, describes all of the bundle
information for the update. Update content produced by mixer is then published
to a web server and consumed by clients via swupd. Refer to
:ref:`swupd <swupd-guide>` for additional information regarding updates and
update content.
content, update metadata, as well as a complete image. The OS content
includes all files in an update, as well as zero- and delta-packs for improved update performance. The update metadata, stored as manifests, describes all of the bundle information for the update. Update content produced by mixer is then published to a web server and consumed by clients via swupd. Refer to :ref:`swupd <swupd-guide>` for additional information regarding updates and update content.
How it works
************
@@ -67,7 +60,7 @@ Prerequisites
If you use a proxy server, you must set your proxy environment variables and
create a proxy configuration file for the Docker daemon and container.
Consult your IT department for the correct values if you are behind a
Consult your IT department for the correct values if you are behind a
corporate proxy.
Refer to `Configure Docker proxy info`_ for instruction.
@@ -232,8 +225,6 @@ mixer for a new mix.
CONTENTURL="http://192.168.25.52"
VERSIONURL="http://192.168.25.52"
Example 2: Create a simple mix
==============================
@@ -253,6 +244,27 @@ set to get a smaller kernel image, which will also be faster to load.
mixer bundle remove kernel-native
mixer bundle add kernel-kvm
#. In this case, we will add the `editors` bundle from upstream, but we will
remove the `joe` editor.
.. code-block:: bash
mixer bundle add editors
mixer bundle edit editors
#. Use an editor and manually remove `joe` from the bundle definition.
.. code-block:: bash
$EDITOR ./local-bundles/editors
#. List the bundles in the mix again to confirm removal.
.. code-block:: bash
mixer bundle list --tree
#. Build bundles:
.. code-block:: bash
@@ -343,8 +355,8 @@ Example 3: Deploy updates to target
===================================
The image created in Example 2 is directly bootable in QEMU. In this example,
we'll boot the image from Example 2 to verify it, and update the image from mix
version 10 (from which the image was built), to mix version 20.
we'll boot the image from Example 2 to verify it, and update the image from
mix version 10 (from which the image was built), to mix version 20.
#. Set up the QEMU environment.
@@ -381,13 +393,17 @@ version 10 (from which the image was built), to mix version 20.
swupd bundle-list
swupd bundle-list -a
.. note::
You cannot see the curl bundle that you added in Example 2 because
your mix is still on version 10.
#. Now we will add the `editors` bundle that we modified.
Check for updates. You should see that version 20 is available. Use swupd to
update your mix:
.. code-block:: bash
swupd bundle add editors
#. Try to start the `joe` editor. It should not appear because we removed it
from the original `editors` bundle.
#. Next we will update from version 10 to 20 to capture the newly
available bundles. Use :command:`swupd` to update your mix:
.. code-block:: bash
@@ -395,7 +411,7 @@ version 10 (from which the image was built), to mix version 20.
swupd update
swupd bundle-list -a
Now your mix should be at version 20 and curl is now available. Try using
#. Now your mix should be at version 20 and curl is now available. Try using
curl. This will fail because curl is not yet installed:
.. code-block:: console
@@ -416,6 +432,7 @@ version 10 (from which the image was built), to mix version 20.
poweroff
.. Example: Create a mix with custom RPM
.. -------------------------------------
.. TODO future example to show copy into local-rpms...
@@ -538,30 +555,34 @@ Format version
Compatible versions of an OS are tracked with an OS *compatibility epoch*.
Versions of an OS within an epoch are fully compatible and can update to any
other version within that epoch. The compatibility epoch is set as the `Format`
variable in the :file:`mixer.state` file. Variables in the :file:`mixer.state`
are used by mixer between executions and should not be manually changed.
other version within that epoch. The compatibility epoch is set as the
`Format` variable in the :file:`mixer.state` file. Variables in the
:file:`mixer.state` are used by mixer between executions and should not be
manually changed.
If `Format` increments to a new epoch (a "format bump"), the OS has changed in
such a way that updating from build M in format X to build N in format Y will
not work. Generally, this scenario occurs when the software updater or the software
has a change such that it is no longer compatible with the previous update
scheme, or when a package is removed from the update stream and the update
must ensure the files associated with that package are removed from the system.
A format bump is like modifying the foundation of a house to create a new
level. If `Format` increments to a new epoch (a "format bump"), the OS has
changed in such a way that updating from build A in format X to build B in
format Y will not work.
A format bump is required when:
* The software updater, :command:`swupd`, or the software is no longer
compatible with the previous update scheme
* A package is removed from the update stream and the update must ensure the
files associated with that package are removed from the system
Using a format increment, we make sure pre- and co-requisite changes flow out
with proper ordering. The updated client will only update to the latest
release in its respective format version, unless overridden by command line
flags. In this way, we can guarantee that all clients update to the final version
in their given format.
flags. In this way, we can guarantee that all clients update to the final
version in their given format.
The given format *must* contain all the changes needed to understand the content
built in the next format. Only after reaching the final release in the old
format can a client continue to update to releases in the new format.
The given format *must* contain all the changes needed to understand the content built in the next format. Only after reaching the final release in the old format can a client continue to update to releases in the new format.
The format version is incremented only when a compatibility breakage is
introduced. Normal updates, such as updating a software package, do not require a
format increment.
introduced. Normal updates, such as updating a software package, do not require a format increment.
.. rst-class:: content-collapse
@@ -569,44 +590,41 @@ Bundles
=======
mixer stores information about the bundles included in a mix in a flat file
called :file:`mixbundles`, which is located in the path set by the VERSIONS_PATH
variable in :file:`builder.conf`. :file:`mixbundles` is automatically created
when the mix is initiated. mixer will refresh the file each time you change the
bundles in the mix.
called :file:`mixbundles`, which is located in the path set by the VERSIONS_PATH variable in :file:`builder.conf`. :file:`mixbundles` is automatically created when the mix is initiated. mixer will refresh the file each time you change the bundles in the mix.
Bundles can include other bundles. Nested bundles can themselves include other
bundles. If you see an unexpected bundle in your mix, it is likely a nested
bundle in one of the bundles you explicitly added.
Bundles can include other bundles. Nested bundles can themselves include
other bundles. If you see an unexpected bundle in your mix, it is likely a
nested bundle in one of the bundles you explicitly added.
A bundle will fill into one of two categories: upstream or local. Upstream
bundles are those provided by |CL|. Local bundles are either modified upstream
bundles or new local bundles.
bundles are those provided by |CL|. Local bundles are either modified upstream bundles or new local bundles.
Upstream bundles
----------------
mixer automatically downloads and caches upstream bundle definition files. These
definition files are stored in the upstream-bundles directory in the workspace.
Do not modify the files in this directory. This directory is simply a mirror for
mixer to use. mixer will automatically delete the contents of this directory
before repopulating it on-the-fly if a new version must be downloaded.
mixer automatically downloads and caches upstream bundle definition files.
These definition files are stored in the upstream-bundles directory in the
workspace. Do not modify the files in this directory. This directory is
simply a mirror for mixer to use. mixer will automatically delete the
contents of this directory before repopulating it on-the-fly if a new
version must be downloaded.
The mixer tool automatically caches the bundles for the |CL| version configured
in the :file:`upstreamversion` file. mixer also cleans up old versions once they
are no longer needed.
The mixer tool automatically caches the bundles for the |CL| version
configured in the :file:`upstreamversion` file. mixer also cleans up old
versions once they are no longer needed.
Local bundles
-------------
Local bundles are bundles that you create, or are edited versions of upstream
bundles. Local bundle definition files are stored in the local-bundles directory
in the workspace. The LOCAL_BUNDLE_DIR variable sets the path of this directory
in the :file:`builder.conf` file.
bundles. Local bundle definition files are stored in the local-bundles
directory in the workspace. The LOCAL_BUNDLE_DIR variable sets the path of this directory in the :file:`builder.conf` file.
*mixer always checks for local bundles first and the upstream bundles second.*
So bundles in the local-bundles directory will always take precedence over any
upstream bundles that have the same name. This precedence enables you to copy
upstream bundles locally, and edit into a local variation.
*mixer always checks for local bundles first and the upstream bundles
second.* So bundles in the local-bundles directory will always take
precedence over any upstream bundles that have the same name. This
precedence enables you to copy upstream bundles locally, and edit into a
local variation.
Bundle configuration
--------------------
@@ -622,13 +640,11 @@ file in your favorite editor, making the desired edits, and saving your changes.
.. note::
Removing bundles from a mix: By default, removing a bundle will only
remove the bundle from the mix. The local bundle definition file will still
remain. To completely remove a bundle, including its local bundle definition
file, use the :command:`--local` flag.
remove the bundle from the mix. The local bundle definition file will
still remain. To completely remove a bundle, including its local bundle definition file, use the :command:`--local` flag.
If you remove the bundle definition file for a local, edited version of an
upstream bundle in a mix, the mix reverts to reference the original upstream
version of the bundle.
upstream bundle in a mix, the mix reverts to reference the original upstream version of the bundle.
.. rst-class:: content-collapse
@@ -656,8 +672,8 @@ Pull Docker container manually (optional)
-----------------------------------------
By default, mixer automatically pulls a Docker container for mixing if one
does not already exist. If you need to troubleshoot the mixer container, it may
be useful to manually pull a mixer Docker container.
does not already exist. If you need to troubleshoot the mixer container, it
may be useful to manually pull a mixer Docker container.
Versions of the mixer Docker container are available under the tags for the
`clearlinux/mixer repo <https://hub.docker.com/r/clearlinux/mixer/tags/>`_
@@ -695,7 +711,7 @@ If needed, use these steps to configure the Docker proxy information.
.. code-block:: bash
sudo mkdir -p /etc/systemd/system/docker.service.d
#. Create :file:`/etc/systemd/system/docker.service.d/http-proxy.conf` and
add the following using your own proxy values:
@@ -711,7 +727,7 @@ If needed, use these steps to configure the Docker proxy information.
sudo systemctl daemon-reload
Configure the Docker container proxies, to pass proxy settings to
Configure the Docker container proxies, to pass proxy settings to
containers:
#. Create a directory for your container config:
@@ -764,8 +780,8 @@ a firewall.
Set up a nginx web server for mixer
===================================
A web server is needed to host your update content. In this example, we use the
nginx web server, which comes with |CL|.
A web server is needed to host your update content. In this example, we use
the nginx web server, which comes with |CL|.
Set up a nginx web server for mixer with the following steps:
@@ -781,9 +797,9 @@ Set up a nginx web server for mixer with the following steps:
sudo mkdir -p /var/www
#. Create a symbolic link between your workspace updates and the updates on the
local nginx web server. In this example, `$HOME/mixer` is the workspace for
the mix.
#. Create a symbolic link between your workspace updates and the updates on
the local nginx web server. In this example, `$HOME/mixer` is the
workspace for the mix.
.. code-block:: bash