mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-06-29 17:26:01 +00:00
Removes mixin.rst and all references to it. (#506)
- Closes #478 Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
michael vincerra
@@ -102,6 +102,5 @@ Related topics
|
||||
|
||||
* :ref:`autospec`
|
||||
* :ref:`mixer`
|
||||
* :ref:`mixin`
|
||||
|
||||
.. _autospec readme: https://github.com/clearlinux/autospec
|
||||
|
||||
@@ -11,10 +11,8 @@ needs.
|
||||
However, if you need additional customization or content, |CL| provides the
|
||||
mixer tool. Depending on your needs, the mixer tool allows you to:
|
||||
|
||||
1. :ref:`create-mix` to create a distinct derivative of the |CL| that
|
||||
* :ref:`create-mix` to create a distinct derivative of the |CL| that
|
||||
contains your custom software.
|
||||
2. :ref:`create-mixin` to add custom bundles but also keep updating the OS
|
||||
from upstream.
|
||||
|
||||
.. _create-mix:
|
||||
|
||||
@@ -43,31 +41,6 @@ act as your own OSV. There is a greater level of responsibility, requiring
|
||||
more infrastructure and processes to adopt. However, with this approach, you
|
||||
have a higher degree of control and customization of your custom |CL|.
|
||||
|
||||
|
||||
.. _create-mixin:
|
||||
|
||||
Create a mixin
|
||||
==============
|
||||
|
||||
The second option is to use the :command:`mixin` tool, a light wrapper for
|
||||
mixer, to create custom bundles and sideload them into your upstream version
|
||||
of |CL|. A mixin is useful when you need to add custom or 3rd
|
||||
party content but want to keep on the upstream update cycle, as shown in
|
||||
Figure 2. You can also create new bundles using upstream packages.
|
||||
|
||||
.. figure:: figures/mixer-about-2.png
|
||||
:scale: 75%
|
||||
:alt: Creating a custom mix.
|
||||
|
||||
Figure 2: With a mixin you can add custom bundles, but stay on upstream.
|
||||
|
||||
Mixin is primarily intended for end users. It is easier to adopt as it does
|
||||
not require breaking from upstream or acting as an OSV. With mixin
|
||||
|
||||
* You are responsible for maintaining and testing your custom bundle(s).
|
||||
* You retain access to all upstream bundles and updates.
|
||||
* You can easily revert your system back to the upstream version.
|
||||
|
||||
Related topics
|
||||
==============
|
||||
|
||||
@@ -76,7 +49,6 @@ mixer and related topics to decide which customization approach is best for
|
||||
you.
|
||||
|
||||
* :ref:`mixer`
|
||||
* :ref:`mixin`
|
||||
* :ref:`bundles-about`
|
||||
* :ref:`swupd-about`
|
||||
* :ref:`deploy-at-scale`
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
Deploy at Scale
|
||||
###############
|
||||
|
||||
Once you are comfortable with |CL-ATTR| :ref:`concepts <concepts>`, your next step
|
||||
as a system administrator is to understand how to deploy |CL|
|
||||
Once you are comfortable with |CL-ATTR| :ref:`concepts <concepts>`, your
|
||||
next step as a system administrator is to understand how to deploy |CL|
|
||||
at scale in your environment.
|
||||
|
||||
In this document the term *endpoint* refers to a system targeted for
|
||||
@@ -32,39 +32,10 @@ Different business scenarios call for different deployment methodologies.
|
||||
distribution or the option to fork away from the |CL| distribution and
|
||||
act as your own :abbr:`OSV (Operating System Vendor)`.
|
||||
|
||||
Below are overviews of both approaches and some considerations.
|
||||
Below is an overview of some considerations.
|
||||
|
||||
Option #1: Use the |CL| as the upstream origin (mixin)
|
||||
------------------------------------------------------
|
||||
|
||||
This approach is *easier to adopt* by relying on the |CL| upstream for
|
||||
packaging updates for you to deploy.
|
||||
|
||||
Custom software or packages that are not available in a preformed bundle
|
||||
can be added using the `mixin process`_ to form a custom bundle.
|
||||
If custom bundles are needed, you will be responsible for maintaining
|
||||
the custom bundle(s) and testing between |CL| releases in your environment,
|
||||
while the rest of the operating system and preformed bundles come from the
|
||||
|CL| upstream.
|
||||
|
||||
#. Ensure |CL| systems are able to be inventoried, managed, and orchestrated
|
||||
to coordinate software updates.
|
||||
|
||||
#. With autoupdate enabled, |CL| is updated daily, however you may wish to
|
||||
act as an intermediary buffer between the OS releases. If you do decide
|
||||
to act as a gate to |CL| versions, define a desired release cadence for
|
||||
yourself which is realistic with the operational expectations of your
|
||||
environment.
|
||||
|
||||
#. Use a web caching proxy for |CL| updates for devices connected to
|
||||
a local area network (LAN), like a datacenter, to increase the speed
|
||||
and resiliency of updates from the |CL| update servers.
|
||||
|
||||
Your caching proxy server is just like any other web application.
|
||||
|WEB-SERVER-SCALE|
|
||||
|
||||
Option #2: Create your own Linux distribution (mix)
|
||||
---------------------------------------------------
|
||||
Create your own Linux distribution (mix)
|
||||
----------------------------------------
|
||||
|
||||
This approach forks away from the |CL| upstream and has you act as your own
|
||||
:abbr:`OSV (Operating System Vendor)` by leveraging the `mixer process`_ to
|
||||
@@ -267,7 +238,6 @@ Continuously test its use; Automate its use by redeploying |CL| and
|
||||
application on new hosts. This naturally minimizes configuration drift,
|
||||
challenges your monitoring systems, and business continuity plans.
|
||||
|
||||
.. _`mixin process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixin
|
||||
.. _`mixer process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixer
|
||||
.. _`downloads page`: https://clearlinux.org/downloads/
|
||||
.. _`containers page`: https://clearlinux.org/downloads/containers
|
||||
|
||||
@@ -4,6 +4,7 @@ Guides
|
||||
######
|
||||
|
||||
The following guides provide step-by-step instructions on using |CL|.
|
||||
Note: As of 22 May 2019 :file:`mixin` is no longer supported.
|
||||
|
||||
Tooling
|
||||
=======
|
||||
|
||||
@@ -327,7 +327,7 @@ Test packaged software
|
||||
|
||||
After software has been packaged with autospec, the resulting RPMs can be
|
||||
tested for functionality before being integrated and deployed into a |CL|
|
||||
image with the :ref:`Mixer tool <mixer>` or :ref:`Mixin tool <mixin>`.
|
||||
image with the :ref:`Mixer tool <mixer>`.
|
||||
|
||||
The |CL| development tooling offers two ways to quickly test autospec
|
||||
generated RPMs.
|
||||
@@ -500,7 +500,6 @@ Related topics
|
||||
**************
|
||||
|
||||
* :ref:`Mixer tool <mixer>`
|
||||
* :ref:`Mixin tool <mixin>`
|
||||
|
||||
.. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh
|
||||
.. _`Makefile.common file on GitHub`: https://github.com/clearlinux/common/blob/master/Makefile.common
|
||||
|
||||
@@ -829,7 +829,6 @@ Related topics
|
||||
**************
|
||||
|
||||
* :ref:`About mixer <mixer-about>`
|
||||
* :ref:`mixin`
|
||||
* :ref:`autospec-about`
|
||||
* :ref:`bundles-about`
|
||||
* :ref:`swupd-about`
|
||||
|
||||
@@ -1,191 +0,0 @@
|
||||
.. _mixin:
|
||||
|
||||
mixin
|
||||
#####
|
||||
|
||||
mixin is a tool provided in the |CL-ATTR| that allows users to add custom
|
||||
content to their client systems and still receive updates from their upstream OS
|
||||
vendor.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
mixin uses the mixer tool to generate a local update for client systems. With
|
||||
the mixin tool, a user can add remote RPM repositories or local RPMs and mix
|
||||
them into their update stream, while continuing to get upstream bundles and
|
||||
updates. The metadata generated from the mixin tool is merged with the upstream
|
||||
metadata to provide a single source of update content, which swupd uses to
|
||||
perform updates.
|
||||
|
||||
The mixin tool is included in the :command:`mixer` bundle.
|
||||
|
||||
How to use
|
||||
**********
|
||||
|
||||
Learn the mixin tool set up and workflow.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
Install the :command:`mixer` bundle to add the mixin tool. Refer to
|
||||
`Install a bundle`_ for more details.
|
||||
|
||||
Workflow
|
||||
========
|
||||
|
||||
The following steps show how to create and add a custom bundle with the mixin
|
||||
tool:
|
||||
|
||||
#. Add or create a new repo(s)
|
||||
|
||||
mixin pulls packages to build your custom bundle from locations referred to
|
||||
as repos. There are two default repos for mixin:
|
||||
|
||||
* upstream
|
||||
* local
|
||||
|
||||
Additional repos can be added, such as other locations on your local system
|
||||
or remote repos.
|
||||
|
||||
RPMs must be built specifically for |CL| in order for them to work properly.
|
||||
Refer to :ref:`autospec` for instruction on creating RPMs for |CL|.
|
||||
|
||||
#. Create a custom bundle with desired RPMs
|
||||
|
||||
Add the desired packages to your new bundle and build the bundle. By default,
|
||||
the bundle will be named after its parent repo.
|
||||
|
||||
The first time you build the bundle, mixer will create a new OS version by
|
||||
taking your current upstream |CL| version and multiplying it by 1000. For
|
||||
example, if your upstream version is 27650, your custom version will be
|
||||
27650000. For each subsequent call to mixin, mixer will increment the version
|
||||
by 10.
|
||||
|
||||
View the `mixin man page`_ for more information on mixin commands.
|
||||
|
||||
#. Update system to make custom bundle available
|
||||
|
||||
Update your system using swupd to make your custom bundle accessible.
|
||||
|
||||
When you first create your mix, you will have to do a one-time migration to
|
||||
your custom mix as part of the update. After you migrate, the system version
|
||||
switches over to your last custom version number as noted in the previous
|
||||
step. As long as you remain on your custom version of |CL| you can continue
|
||||
to create and add new bundles to your mix with no extra migration step.
|
||||
|
||||
#. Install custom bundles
|
||||
|
||||
Install your custom bundle using the normal swupd :command:`bundle-add`
|
||||
command.
|
||||
|
||||
View the `swupd man page`_ for more information on swupd commands.
|
||||
|
||||
Examples
|
||||
********
|
||||
|
||||
Complete all `Prerequisites`_ before using these examples.
|
||||
|
||||
Example 1: Add custom helloclear bundle
|
||||
=======================================
|
||||
|
||||
This example shows the basic steps of adding a custom bundle from a local repo.
|
||||
|
||||
#. Check that :command:`helloclear` does not exist on your system:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
helloclear
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
helloclear: command not found
|
||||
|
||||
#. Follow the "Build a new RPM" example from :ref:`autospec` to create a new
|
||||
`helloclear` RPM.
|
||||
|
||||
The resulting RPMs are in `~/clearlinux/packages/helloclear/rpms`.
|
||||
|
||||
#. Create a new repo.
|
||||
|
||||
#. Create a local repo folder and copy the new `helloclear` RPM files into
|
||||
the repo:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir ~/mixin-repo
|
||||
cp ~/clearlinux/packages/helloclear/rpms/helloclear-v1.0-1.x86_64.rpm ~/mixin-repo
|
||||
cp ~/clearlinux/packages/helloclear/rpms/helloclear-bin-v1.0-1.x86_64.rpm ~/mixin-repo
|
||||
|
||||
#. Create the repo data:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/mixin-repo
|
||||
createrepo_c .
|
||||
|
||||
#. Add the repo name:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixin repo add mylocalrepo file://$HOME/mixin-repo/
|
||||
|
||||
#. Create custom bundle with the new `helloclear` RPM. Add `helloclear` to the
|
||||
:command:`helloclear-bundle` bundle and build the bundle:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixin package add helloclear --bundle helloclear-bundle
|
||||
sudo mixin build
|
||||
|
||||
#. Migrate your |CL| to your custom mix. Check your version before and after the
|
||||
update to see the switch to your custom mix:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd check-update
|
||||
sudo swupd update --migrate
|
||||
sudo swupd check-update
|
||||
|
||||
#. Install your custom bundle. Check that the `helloclear-bundle` is now
|
||||
available and install it to your system:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-list -a | grep helloclear-bundle
|
||||
sudo swupd bundle-add helloclear-bundle
|
||||
|
||||
#. Test for `helloclear` again to see that it is installed:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
helloclear
|
||||
|
||||
#. Revert your system back to upstream (optional). This example reverts back to
|
||||
upstream version 27650:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo swupd verify --fix --picky --force -m 27650 -C /usr/share/clear/update-ca/Swupd_Root.pem
|
||||
sudo swupd clean --all
|
||||
sudo swupd check-update
|
||||
|
||||
Related topics
|
||||
**************
|
||||
|
||||
* :ref:`About mixer <mixer-about>`
|
||||
* :ref:`mixer`
|
||||
* :ref:`autospec-about`
|
||||
* :ref:`bundles-about`
|
||||
* :ref:`swupd-about`
|
||||
|
||||
.. _mixin man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixin.1.rst
|
||||
.. _swupd man page: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst
|
||||
.. _Install a bundle: https://clearlinux.org/documentation/clear-linux/guides/maintenance/swupd-guide#adding-a-bundle
|
||||
Reference in New Issue
Block a user