Skip to content

Commit

Permalink
Add info about fioctl auto update
Browse files Browse the repository at this point in the history 
Added a note in the getting started guide, a slightly more detailed note
in the user guide, and an additional somewhat related note in team based
access.

QA: information will be verified during PR process. Rendered html
checked, no errors spotted. No linter errors that need correcting.

This commit addresses issue FFTK 2905

Signed-off-by: Katrina Prosise <katrina.prosise@foundries.io>
  • Loading branch information
@kprosise
kprosise committed Nov 28, 2023
1 parent adcd244 commit 23d492b
Show file tree
Hide file tree
Showing 3 changed files with 56 additions and 7 deletions.
16 changes: 9 additions & 7 deletions source/getting-started/install-fioctl/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Installing Fioctl
=================

:ref:`Fioctl™ <ref-fioctl>` is a simple tool for interacting with the Foundries.io REST API.
:ref:`Fioctl™ <ref-fioctl>` is a simple tool for interacting with the Foundries.io™ REST API.

Check failure on line 6 in source/getting-started/install-fioctl/index.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Fioctl-trademark] 'Fioctl' should be marked as a trademark first time it occurs in body of text.

Raw Output:
{"message": "[Fio-docs.Fioctl-trademark] 'Fioctl' should be marked as a trademark first time it occurs in body of text.", "location": {"path": "source/getting-started/install-fioctl/index.rst", "range": {"start": {"line": 6, "column": 7}}}, "severity": "ERROR"}

Check failure on line 6 in source/getting-started/install-fioctl/index.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

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

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Fioctl' instead of 'fioctl'", "location": {"path": "source/getting-started/install-fioctl/index.rst", "range": {"start": {"line": 6, "column": 20}}}, "severity": "ERROR"}

.. seealso::
Fioctl is based on Foundries.io's `ota-lite API <https://api.foundries.io/ota/>`_.
Expand All @@ -27,10 +27,12 @@ Installation
Manual Installation
^^^^^^^^^^^^^^^^^^^

We use `Github Releases`_ to distribute static golang binaries.
We use `GitHub Releases`_ to distribute static golang binaries.

.. tip::
Repeating the following steps will overwrite an existing binary, useful for updating or changing version.
Fioctl v0.36 and later has an auto-update feature.

Check failure on line 33 in source/getting-started/install-fioctl/index.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Fioctl-trademark] 'Fioctl' should be marked as a trademark first time it occurs in body of text.

Raw Output:
{"message": "[Fio-docs.Fioctl-trademark] 'Fioctl' should be marked as a trademark first time it occurs in body of text.", "location": {"path": "source/getting-started/install-fioctl/index.rst", "range": {"start": {"line": 33, "column": 4}}}, "severity": "ERROR"}
Run ``fioctl version`` to check for an update, then run ``fioctl version --update-to <version>``.
For more details checkout the :ref:`Fioctl user guide <ug-fioctl>`.

.. tabs::

Expand Down Expand Up @@ -64,7 +66,7 @@ We use `Github Releases`_ to distribute static golang binaries.
.. attention::
Make sure you have ``curl`` installed.

1. Download a Darwin binary from the `Github Releases`_ page to a directory on your ``PATH``.
1. Download a Darwin binary from the `GitHub Releases`_ page to a directory on your ``PATH``.

For example, to download version |fioctl_version| on macOS, define the version:

Expand All @@ -91,7 +93,7 @@ We use `Github Releases`_ to distribute static golang binaries.

.. group-tab:: Windows

1. Download a Windows binary from the `Github Releases`_ page.
1. Download a Windows binary from the `GitHub Releases`_ page.
2. Put it in a folder of your choosing and rename it to ``fioctl.exe``
3. Press ``Win + R`` and type ``SystemPropertiesAdvanced``
4. Press ``enter`` or click ``OK``.
Expand All @@ -112,7 +114,7 @@ Authenticating Fioctl
#####################

With :ref:`ref-fioctl` installed, authenticate it with our backend.
For this, you will generate OAuth2 application credentials for interacting with the FoundriesFactory API:
For this, you will generate OAuth2 application credentials for interacting with the FoundriesFactory® API:

.. prompt:: bash host:~$, auto

Expand Down Expand Up @@ -190,7 +192,7 @@ The following command can be used to test the ``fioctl`` configuration.
.. seealso::
:ref:`ref-fioctl` documentation.

.. _Github Releases: https://github.com/foundriesio/fioctl/releases
.. _GitHub Releases: https://github.com/foundriesio/fioctl/releases

.. _gs-git-config:

Expand Down
12 changes: 12 additions & 0 deletions source/user-guide/account-management/team-based-access.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ The member then has a combined list of scopes:
The user now has read **and** write (update) access to the CI,
while retaining the read-only scopes for the other resources.


.. _Access to Device Groups:

Team Based Access to Device Groups
Expand Down Expand Up @@ -137,3 +138,14 @@ Therefore, members of this team can modify the ``test-lab-devices`` group and it
.. figure:: /_static/userguide/account-management/team-with-group-and-write-access.png
:align: center
:alt: "lab-dev-users" scopes: read-update team with a device group


.. _team-based-access-tuf:

Changes to TUF Root
-------------------

With Fioctl® v0.35 and newer, if someone makes changes to TUF root, others will be required to upgrade to the same version if they wish to make changes.

Check warning on line 148 in source/user-guide/account-management/team-based-access.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/user-guide/account-management/team-based-access.rst", "range": {"start": {"line": 148, "column": 1}}}, "severity": "INFO"}
This is to prevent accidental eraser of the TUF keys ownership information.


35 changes: 35 additions & 0 deletions source/user-guide/fioctl/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,41 @@ Prerequisites

* Completion of the getting started guide.


.. _ug-fioctl-auto-update:

Auto Updating
-------------

``fioctl version --update-to <version>``
Fioctl v0.36 and later can be updated—rather securely, via TUF—without the need to manually reinstall the binary.

.. code-block:: console
# check if an update is available:
host:~$ fioctl version
v0.37-24-gd450f5b
Update available: 0.38.0
https://github.com/foundriesio/fioctl/releases/download/v0.38/fioctl-linux-amd64
# update by running:
host:~$ fioctl version --update-to 0.38.0
v0.37-24-gd450f5b
Downloading update: https://github.com/foundriesio/fioctl/releases/download/v0.38/fioctl-linux-amd64
Saving new version to /var/code/vs-code-server-config/fioctl/bin/fioctl-linux-amd64
.. important::

A note about write permissions:

It is likely that you will need to gain write privilege to update.
This *can* be done via ``sudo``, assuming it is not a read-only partition.
However, also consider running ``sudo su`` within a new terminal.
This is to avoid having sudo holding a session, and some privilege escalation risks.

.. seealso::
:ref:`Updating Fioctl version for writing to TUF Root <team-based-access-tuf>`

.. _ug-fioctl-enable-apps:

Enabling/Disabling Apps
Expand Down

0 comments on commit 23d492b

Please sign in to comment.