Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ug: introduce waves page #803

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

ug: introduce waves page #803

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added source/_static/userguide/waves/waves-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 3 additions & 1 deletion source/glossary/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,8 +290,9 @@ Glossary
Production Device
A device with a flag in its certificate which enables it to receive production updates.

* :ref:`Factory Registration Reference Manual, Registering Proudction Devices by Default <ref-factory-registration-ref>`
* :ref:`Factory Registration Reference Manual, Registering Production Devices by Default <ref-factory-registration-ref>`
* :ref:`Reference Manual, Production Targets for Production Devices <ref-production-targets>`
* :ref:`User Guide, Waves<ref-waves-ug>`

Production Targets
:term:`TUF` Targets delivered to production devices during an :term:`OTA Update`.
Expand Down Expand Up @@ -329,6 +330,7 @@ Glossary
The FoundriesFactory method for adding a specific CI Targets version to production Targets.
Provisions it to production devices in a controlled way.

* :ref:`User Guide, Waves<ref-waves-ug>`
* :ref:`Production Targets Reference Manual, Wave <ref-production-targets>`

Wave Rollout
Expand Down
2 changes: 1 addition & 1 deletion source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ The FoundriesFactory Platform brings together key features and functions for dev
reference-manual/security/offline-keys
reference-manual/security/factory-keys
reference-manual/factory/sboms
reference-manual/ota/production-targets
user-guide/waves/waves
user-guide/device-gateway-pki/device-gateway-pki
user-guide/rotating-cert
user-guide/troubleshooting/troubleshooting
Expand Down
4 changes: 2 additions & 2 deletions source/reference-manual/ota/production-targets.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Alternatively, you can provide the device UUIDs to update::
fioctl waves rollout v2.0-update --uuids=ab8ecb00-8ed4-42ff-90b2-815b371c0f86,7a733e81-f948-43a9-a358-56f3deb5f184

Check the ``fioctl waves rollout --help`` command for all available options,
or look at the :ref:`Advanced Usage <ref-rm-wave-adv>` for more complex workflows.
or look at the :ref:`Advanced Usage <ref-rm-prod-target-adv>` for more complex workflows.
Hopefully, they should suit your specific production release lifecycle needs.

To monitor the status of your Factory OTA updates, use the ``fioctl status`` command.
Expand All @@ -128,7 +128,7 @@ However, other production devices will not be updated, and will continue to run

We recommend using a production target after a validated and completed wave to flash new production devices.

.. _ref-rm-wave-adv:
.. _ref-rm-prod-target-adv:

Advanced Usage
--------------
Expand Down
2 changes: 2 additions & 0 deletions source/reference-manual/security/factory-registration-ref.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ However, it does have a couple caveats:
* ``fioctl devices list-denied``
* ``fioctl devices delete-denied``

.. _ref-production-registration:

Registering Production Device by Default
----------------------------------------

Expand Down
2 changes: 2 additions & 0 deletions source/reference-manual/security/offline-keys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,8 @@ Otherwise, it will be impossible to make any future updates to the Factory TUF k
That will lead to the inability to deliver new :ref:`Over-the-Air (OTA) updates <ref-ota>` to your Factory devices.
Therefore, after each TUF root key rotation, we recommend that you `Backup Offline TUF Keys`_ as described below.

.. _ref-offline-targets-keys:

How to Rotate Offline TUF Targets Key
-------------------------------------

Expand Down
145 changes: 145 additions & 0 deletions source/user-guide/waves/waves.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
.. _ref-waves-ug:

Waves and Production Targets
============================

Waves is the FoundriesFactory mechanism to promote and deliver updates to :ref:`production devices <ref-production-registration>`.

Check warning on line 6 in source/user-guide/waves/waves.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.FoundriesFactory-trademark] 'FoundriesFactory' should be marked as an unregistered trademark first time it occurs in body of text and used as an adjective.

Raw Output:
{"message": "[Fio-docs.FoundriesFactory-trademark] 'FoundriesFactory' should be marked as an unregistered trademark first time it occurs in body of text and used as an adjective.", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 6, "column": 14}}}, "severity": "WARNING"}
It allows deciding which updates are promoted to production, with granular control of how the updates are delivered across the field.
It also provides additional security as only Factory Owners and Admins in possession of TUF targets keys are allowed perform these actions.

Check warning on line 8 in source/user-guide/waves/waves.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 8, "column": 89}}}, "severity": "INFO"}

Suggested Flow
--------------

When devices are registered to production, they only update to :ref:`ref-production-targets`.

Below you can find the standard flow to promote a target to a Production Target using Waves (``fioctl waves``).

.. note::
This process can only be performed by Factory Owners and Admins owning the :ref:`Offline TUF Targets keys <ref-offline-targets-keys>`.

Check warning on line 18 in source/user-guide/waves/waves.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 18, "column": 93}}}, "severity": "INFO"}

.. image:: /_static/userguide/waves/waves-flow.png
:width: 400
:align: center
:alt: Waves subcommands suggested flow

Waves Init (``fioctl waves init``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Starts a new Wave on the wanted Target.
* No updates delivered at this point.
* Wave Status: ``Active``.

Waves Rollout (``fioctl waves rollout``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Delivers the update to a specific device group.
* Multiple rollout commands can be issued for a single wave.
* Different wave rollouts can happen in parallel.
* Optional stage, but recommended.
* Options for granular control are available at this stage, please check command helper and :ref:`ref-production-targets`.
* Wave Status: ``Active``.

Waves Complete (``fioctl waves complete``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Delivers the update to all production devices following this wave tag.
* Only after Wave Complete, this Target becomes a Production Target.
* Wave Status: ``Complete``.

Waves Cancel (``fioctl waves cancel``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Cancels an active wave.
* Devices that updated prior to Waves Cancel stays in the updated version.
* This Target does not become a Production Target.
* Wave Status: ``Canceled``.

.. tip::
Wave Status can be checked with ``fioctl waves list`` or in the ``Waves`` tab of the Factory.

Below is a summary of Waves and Production Targets status at each wave stage:

.. list-table:: Waves x Production Targets
:header-rows: 1
:align: center

* - Wave Stage
- Wave Status
- Production Target
* - Init
- Active
- No
* - Rollout
- Active
- No
* - Complete
- Complete
- Yes
* - Cancel
- Canceled
- No

Waves Considerations
--------------------

* For production manufacturing, we recommend using only Production Targets. The assumption is that these are the production quality Targets.

* Targets become Production Targets after the Wave Complete step.

* You can get the list of Production Targets with:

.. code-block::

fioctl targets list --production --by-tag <tag>

* You may create as many waves as you need for your release strategy. But, there may be only one active wave per device tag at a time. If you need to roll out more than one wave to one tag, either complete or cancel a previous wave to that tag.

* The Wave Rollout step can be skipped by initializing and completing the wave. This delivers the update across all fleet at once.

* Tags in :ref:`ref-ci-targets` do not conflict with tags in Production Targets.

* This means that both CI and Production Targets can have the same tag and not impact the other class of devices. For example, a production device following the ``release`` tag does not update to a CI Target tagged with ``release`` and vice-versa.

* Up to LmP v95, unexpected downgrades can happen during :ref:`TUF keys rotation <ref-offline-keys>` in case there are devices running on Canceled Waves.

Check warning on line 103 in source/user-guide/waves/waves.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 103, "column": 64}}}, "severity": "INFO"}

* During the TUF keys rotation, the TUF metadata is refreshed, causing the devices to receive a fresh version of the targets list. As a Canceled Wave does not produce a Production Target, devices running on this Wave will update to the last Complete Wave, causing a downgrade. This is expected in terms of the TUF specification.

Check warning on line 105 in source/user-guide/waves/waves.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 105, "column": 16}}}, "severity": "INFO"}

Check warning on line 105 in source/user-guide/waves/waves.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 105, "column": 39}}}, "severity": "INFO"}

Check warning on line 105 in source/user-guide/waves/waves.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'TUF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 105, "column": 313}}}, "severity": "INFO"}

* Starting with v95, downgrades are forbidden by default.

* To avoid this behavior in previous LmP versions, complete a wave for the impacted devices prior to the rotation.

Production Workflow
-------------------

The production workflow and release strategy depend on each use case. Here, we present two approaches for simplified usage.

Keeping the Same Tag
~~~~~~~~~~~~~~~~~~~~

This approach benefits use cases where the whole fleet is expected to be in the same software version.

* Production devices follow a unique general tag, for example ``production``, throughout the entire life cycle.

* When a new release is available, a new wave is created for the ``production`` tag.

* Devices update as soon as this new wave is completed or rolled out to their device group.

Creating New Release Tag
~~~~~~~~~~~~~~~~~~~~~~~~

This approach allows granular controls of the fleet and software versions. It is possible to have multiple stable releases for different usage and versions of the product.

* Production devices follow a release tag, for example ``v1.0``.

* When a new release is available, a new wave is created for the new release tag, for example ``v1.1``.

* Device groups are configured to follow the new release tag, for example for a particular device group:

.. code-block::

fioctl config updates -g <device-group> --tag v1.1

* Devices following the new tag update as soon as this new wave is completed or rolled out to their device group.

.. tip::
For advanced use cases, check :ref:`Production Targets Advanced Usage<ref-rm-prod-target-adv>`.
Loading