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

Merged
merged 1 commit into from
Mar 26, 2025
Merged

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
4 changes: 3 additions & 1 deletion source/reference-manual/security/offline-keys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,11 @@
When rotating the TUF root key, the newly generated key is added to the keys tarball (``root.keys.tgz`` in examples).
That file **must never be lost**.
Otherwise, it will be impossible to make any future updates to the Factory TUF keys.
That will lead to the inability to deliver new :ref:`Over-the-Air (OTA) updates <ref-ota>` to your Factory devices.
After a root role expires, without a root key you will lose an ability to deliver new :ref:`Over-the-Air (OTA) updates <ref-ota>` to your Factory devices.

Check warning on line 68 in source/reference-manual/security/offline-keys.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/security/offline-keys.rst", "range": {"start": {"line": 68, "column": 1}}}, "severity": "INFO"}
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
168 changes: 168 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,168 @@
.. _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``).

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

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 15, "column": 51}}}, "severity": "INFO"}

.. 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
~~~~~~~~~~

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

.. code-block::

fioctl waves init -k ~/path/to/keys/targets.only.key.tgz <wave> <target-number> <tag>

Waves Rollout
~~~~~~~~~~~~~

* Delivers the update to a subset of the fleet (device groups, specific devices by UUID, percentage of the fleet).

Check warning on line 39 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] 'UUID' 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] 'UUID' 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": 39, "column": 86}}}, "severity": "INFO"}
* Multiple rollout commands can be issued for a single wave.
* Different wave rollouts can happen in parallel.
* Optional stage, but recommended for controlled deployment of the production update.
* Options for granular control are available at this stage, please check command helper and :ref:`ref-production-targets`.
* Wave Status: ``Active``.

.. code-block::

fioctl waves rollout <wave> [flags]

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``.

.. code-block::

fioctl waves complete <wave>

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``.

.. code-block::

fioctl waves cancel <wave>

Waves Status Summary
~~~~~~~~~~~~~~~~~~~~

.. 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 127 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": 127, "column": 64}}}, "severity": "INFO"}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks more like a warning that needs to be specified separately, e.g. at the end of this section, wrapped into an actual warning block.


* During the TUF keys rotation, the TUF root 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 131 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": 131, "column": 38}}}, "severity": "INFO"}

* Starting with v95, downgrades are forbidden by default.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is important information. This might need to be flagged or highlighted as a warning or some other mechanism to make it clear that key rotation impacts non completed waves pre v95.


* To avoid this behavior in previous LmP versions, complete a wave for the impacted devices prior to the rotation.
Comment on lines +133 to +135
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these two bullets related? It is not evident from a text flow.
Is this also related to another bullet about v95? (Even less evident).

Anyway, I do agree with Tim that this deserves a separate attention and proper emphasize.
Does it make sense to grab all v95 related nuances into its own thing?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was expecting to have all of this related to the v95 note, as this is the behavior customers are concerned with
Screenshot from 2025-03-14 10-58-20

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will add the v95 related nuances to the release notes page, so I though we could have a bigger warning there

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This screenshot styling actually looks quite good.
If we can group all v95 related notes here similarly to how it was done in the release notes, that would be a reasonable improvement.


* It is not possible to Cancel a Wave after it has been Completed, but its Target can be removed from the Production Targets list by pruning it.
To achieve this, Init then Complete a new Wave for this particular Tag with the `--prune <target-number>` parameter:

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

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 138, "column": 93}}}, "severity": "INFO"}

.. code-block::

fioctl waves init -k ~/path/to/keys/targets.only.key.tgz <new-wave> <target-number> <tag> --prune <target-to-prune>
fioctl waves complete <new-wave>

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

Assuming your production fleet is separated into device groups, where ``canary`` is a small device group for testing purposes.
Here we show a simplified overview of Waves usage in production:

* Production devices are registered to follow a unique tag, for example ``release``.

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

* Rollout this wave for the ``canary`` device group and observe the update results.

* If anything goes wrong with this update, you can cancel the wave at this point.

* It is up to you to define the acceptance criteria for the update.

* New rollouts to device groups or particular devices can be performed at this stage.

* The wave should be completed when you wish to deliver the update to all devices on the fleet following this tag.

With this use case, devices update as soon as this new wave is completed or rolled out to their device group.

.. tip::
For advanced use cases and more granular control of your fleet, check :ref:`Production Targets Advanced Usage<ref-rm-prod-target-adv>`.

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

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Target' instead of 'target'", "location": {"path": "source/user-guide/waves/waves.rst", "range": {"start": {"line": 168, "column": 126}}}, "severity": "INFO"}
Loading