Skip to content

Commit

Permalink
Cleanup of factory reference manual section
Browse files Browse the repository at this point in the history 
Style guide lines applied. Removed link to the Yocto Project layers
section which is part of the LmP reference manual; this was done to make
navigation less confusing, and to keep sections focused.

The section on Factory Sources was placed before the Factory Definition,
for better explanatory flow.

QA steps: Ran linter and addressed issues where possible/appropriate.
Checked html output in browser, no obvious rendering issues discovered.
Ran linkcheck.

This commit addresses FFTK-2790
This commit addresses FFTK-1880
This commit applies to FFTK-2732
This commit applies to FFTK-2730
This commit applies to FFTK-988

Signed-off-by: Katrina Prosise <[email protected]>
  • Loading branch information
@kprosise
kprosise committed Nov 17, 2023
1 parent 411ffca commit 5c97cd7
Show file tree
Hide file tree
Showing 8 changed files with 300 additions and 341 deletions.
105 changes: 58 additions & 47 deletions source/reference-manual/factory/api-access.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
API Access
==========

FoundriesFactory APIs can be accessed with two different methods:
FoundriesFactory® APIs can be accessed via two methods:

#. OAuth2_ tokens managed in the `Application Credentials`_ interface.
#. `OAuth2`_ tokens managed in the `Application Credentials`_ interface.
#. API Tokens managed in the `API tokens`_ interface.

These credentials allow users to access:
Expand All @@ -18,70 +18,81 @@ These credentials allow users to access:
password to Git clone and fetch operations.
* `Factory containers`_. Access is granted by passing an API token as the
password to ``docker login hub.foundries.io``.
* Fioctl uses OAuth2 by default, but can also use API Tokens.
* Fioctl® uses OAuth2 by default, but can also use API Tokens.

All tokens are created with scopes to help limit what they can do.

.. note::
Fioctl® has a :ref:`docker-credential-helper` which simplifies access to
hub.foundries.io.

Common scopes
Fioctl has a :ref:`docker-credential-helper` which simplifies access to

Check failure on line 27 in source/reference-manual/factory/api-access.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/reference-manual/factory/api-access.rst", "range": {"start": {"line": 27, "column": 4}}}, "severity": "ERROR"}
``hub.foundries.io``.

Common Scopes
-------------

Some common scopes users may find handy include:
Some common scopes you may find useful include:

* ``source:read-update`` - Useful for Git.
* ``targets:read, devices:read, ci:read`` - read-only access
for fioctl or REST API
* ``targets:read-update, devices:read-update, ci:read`` - read-update
access for fioctl.
* ``containers:read`` - Useful for running docker commands on
factory containers.
* ``source:read-update``: For Git.
* ``targets:read, devices:read, ci:read``: Read-only access for Fioctl or REST API.
* ``targets:read-update, devices:read-update, ci:read``: Read-update access for Fioctl.
* ``containers:read``: For running docker commands on Factory containers.

Check failure on line 38 in source/reference-manual/factory/api-access.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

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

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Docker' instead of 'docker'", "location": {"path": "source/reference-manual/factory/api-access.rst", "range": {"start": {"line": 38, "column": 37}}}, "severity": "ERROR"}

.. _ref-scopes:

Token Scopes
------------

Scopes define what resources a given token may perform operations on. The
following scopes are supported:
Scopes define what resources a given token may perform operations on.
The following scopes are supported:

Source
^^^^^^

source:read
``source:read``
Can perform git clone/fetch/pull operations.
source:read-update
``source:read-update``
Can perform git push operations.
source:delete
Can delete a reference (git push --delete ...) and force-push (git push -f).
source:create
``source:delete``
Can delete a reference (``git push --delete ...``) and force-push (``git push -f``).
``source:create``
Can create a new references (tags and branches).

containers:read
Can docker pull.
containers:read-update
Can docker push.

ci:read
Can access CI builds `https://api.foundries.io/projects/<factory>/lmp/`.
ci:read-update
This isn’t needed normally because ``source:read-update`` triggers CI.
However, certain custom use-cases that trigger CI builds via
`https://api.foundries.io/projects/<factory>/lmp/builds/` can use this.

devices:read
Can view device(s) `https://api.foundries.io/ota/devices/`.
devices:read-update
Can update configuration on a device
`https://api.foundries.io/ota/devices/<device>/config/`
devices:create
Can create a device (lmp-device-register with an API token).
devices:delete
Can delete a device `https://api.foundries.io/ota/devices/<device>/`

targets:read
Can view targets.json `https://api.foundries.io/ota/factories/<factory>/targets/`.
targets:read-update
Can update targets.json `https://api.foundries.io/ota/factories/<factory>/targets/`.
Containers
^^^^^^^^^^

``containers:read``
Can ``docker pull``.
``containers:read-update``
Can ``docker push``.

CI
^^

``ci:read``
Can access CI builds ``https://api.foundries.io/projects/<factory>/lmp/``.
``ci:read-update``
This is not usually needed as ``source:read-update`` triggers the CI.
However, custom use-cases that trigger CI builds via ``https://api.foundries.io/projects/<factory>/lmp/builds/`` may use this.

Devices
^^^^^^^

``devices:read``
Can view device(s) ``https://api.foundries.io/ota/devices/``.
``devices:read-update``
Can update configuration on a device ``https://api.foundries.io/ota/devices/<device>/config/``
``devices:create``
Can create a device (``lmp-device-register`` with an API token).
``devices:delete``
Can delete a device ``https://api.foundries.io/ota/devices/<device>/``

Targets
^^^^^^^

``targets:read``
Can view ``targets.json`` ``https://api.foundries.io/ota/factories/<factory>/targets/``.
``targets:read-update``
Can update ``targets.json`` ``https://api.foundries.io/ota/factories/<factory>/targets/``.

.. _API Tokens:
https://app.foundries.io/settings/tokens
Expand Down
85 changes: 34 additions & 51 deletions source/reference-manual/factory/ci-webhooks.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,11 @@
CI Webhooks
===========

By default each factory is configured to send
:ref:`email notifications <def-notify>` when CI builds complete.
Customers also have the option of receiving webhooks when builds
complete. Webhooks provide a way to do things like launching
internal workflows.
By default, each Factory is configured to send :ref:`email notifications <def-notify>` when CI builds complete.
You also have the option of receiving *webhooks* when builds complete.
Webhooks provide a way to do things such as launching internal workflows.

Webhook data sent by CI looks like::
Webhook data sent by the CI looks like::

{
"build_id": 67,
Expand All @@ -28,17 +26,6 @@ Webhook data sent by CI looks like::
"tests": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-amd64-partner/tests/"
},
{
"name": "build-armhf",
"url": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-armhf/",
"status": "PASSED",
"log_url": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-armhf/console.log",
"web_url": "https://ci.foundries.io/projects/andy-corp/lmp/builds/67/build-armhf/",
"created": "2021-07-26T18:10:39+00:00",
"completed": "2021-07-26T18:11:10+00:00",
"host_tag": "armhf",
"tests": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-armhf/tests/"
},
{
"name": "build-aarch64",
"url": "https://api.foundries.io/projects/andy-corp/lmp/builds/67/runs/build-aarch64/",
"status": "PASSED",
Expand Down Expand Up @@ -66,9 +53,7 @@ Webhook data sent by CI looks like::
"completed": "2021-07-26T18:19:24+00:00"
}

This message includes an HMAC-SHA256_ HTTP header from the
Foundries `CI engine`_, ``X-JobServ-Sig`` to help authenticate the
sender.
This message includes an `HMAC-SHA256`_ HTTP header from the FoundriesFactory® `CI engine`_, ``X-JobServ-Sig`` to help authenticate the sender.

.. _HMAC-SHA256:
https://en.wikipedia.org/wiki/HMAC
Expand All @@ -78,91 +63,89 @@ sender.
Prerequisites
-------------

The customer will need a server with an HTTP(S) port exposed to the
internet. HTTPS is recommended, but the HMAC signing does help
prevent malicious 3rd parties from tampering with the message body.
You will need a server with an HTTP(S) port exposed to the internet.
HTTPS is recommended, but the HMAC signing also helps prevent malicious 3rd parties from tampering with the message body.

.. note:: Ngrok_ can be a useful tool for prototype work.
.. note::
`Ngrok`_ can be a useful tool for prototype work.

.. _Ngrok:
https://ngrok.com/

Configuring webhooks
Configuring Webhooks
--------------------

Define a webhook secret for HMAC signing::

$ fioctl secrets update webhook-docs-example=UseSomethingGoodHere

This command informs the Foundries backend about a new CI related
secret.
This informs the FoundriesFactory backend about a new CI related secret.

Configuring the Factory
-----------------------

The `factory-config.yml` file in ci-scripts.git will need something
like::
``factory-config.yml`` from ``ci-scripts.git`` will need something like:

.. code-block:: YAML
notify:
webhooks:
- url: https://29171f519f0a.ngrok.io/webhook
secret_name: webhook-docs-example
``secret_name`` ties things together so that the backend will use the correct key when signing the HTTP message.

The ``secret_name`` ties things together so that the backend will
know what key to use when signing the HTTP message.
Once this change is pushed, all builds will send webhooks to the configured server.

Once this change is pushed, all future builds will send webhooks to
the configured server.
Example
-------

A quick example
---------------
A Docker-compose based project has been written to help prototype.
This example uses Ngrok_ so that it can be tested behind firewalls.

A simple project docker-compose based project has been written to
help users prototype. This example uses Ngrok_ so that it can be
tested behind firewalls.
.. note:: Ngrok changes URLs every time it restarts.
This requires the ``factory-config.yml`` file to change as well.

.. note:: Ngrok changes URLs every time it restarts. This requires
the factory-config.yml file to change as well.

Prepare the app
Prepare the App
~~~~~~~~~~~~~~~

::

$ git clone https://github.com/foundriesio/jobserv-webhook-example
$ cd jobserv-webhook-example
$ docker-compose build

Create the secret
Create the Secret
~~~~~~~~~~~~~~~~~

::

# Set secret in backend:
$ fioctl secrets update webhook-docs-example=UseSomethingGoodHere
# Set secret for compose app:
$ echo UseSomethingGoodHere > webhook-secret

Launch the app
Launch the App
~~~~~~~~~~~~~~

::

$ docker-compose up

At this point, close attention must be paid to the docker-compose
logs. Ngrok will print a message like::
At this point, pay attention to the Docker-compose logs.
Ngrok will print a message like::

ngrok-proxy_1 | t=2021-07-26T17:51:15+0000 lvl=info msg="started tunnel" obj=tunnels name=command_line addr=http://webhook:5000 url=https://29171f519f0a.ngrok.io

That tells the URL its proxying with. Take this URL and configure
the factory-config.yml's ``notify.webhooks[0].url`` value.

Push a change
Push a Change
~~~~~~~~~~~~~

Go to a branch in containers.git like "devel" and push and empty
change with::
Go to a branch in ``containers.git`` such as ``devel`` if you have it, and push an empty change with::

$ git commit --allow-empty -m "bump to test webhooks"

Now sit and wait for CI to complete and webhook to be delivered to
the webhook app. It will print the contents of the webhook data.
Wait for it to complete and the webhook to be delivered to the webhook app.
It will print the contents of the webhook data.
8 changes: 5 additions & 3 deletions source/reference-manual/factory/data-retention.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Data Retention Policies
=======================

Understanding data retention policies within a FoundriesFactory can help with the compliance processes for a product.
Understanding data retention policies for Foundries.io™ FoundriesFactory® can help with the compliance processes for a product.
This page explains how data is managed within a Factory.
FoundriesFactory consists of several tightly integrated projects:

Expand All @@ -28,7 +28,7 @@ Customer Data
source.foundries.io
~~~~~~~~~~~~~~~~~~~
Source code like ``containers.git`` lives in Digital Ocean's SFO2 data center where it is periodically backed up.
Backups —but not the source itself— older than 6 months get pruned.
Backups—but not the source itself—older than 6 months get pruned.
Source code gets deleted when a Factory is deleted.

ci.foundries.io
Expand All @@ -55,10 +55,12 @@ This data get pruned periodically, and gets deleted when a Factory is deleted.

api.foundries.io
~~~~~~~~~~~~~~~~

A reverse proxy to other services, and stores no data.

app.foundries.io
~~~~~~~~~~~~~~~~

This service has two components:

* A web view to ``api.foundries.io``
Expand Down Expand Up @@ -108,4 +110,4 @@ Backups over 6 months old get pruned.
ostree.foundries.io
~~~~~~~~~~~~~~~~~~~
Devices pull LmP updates down from this service.
It is managed in a similar way to hub.foundries.io.
It is managed in a similar way to ``hub.foundries.io``.
Loading

0 comments on commit 5c97cd7

Please sign in to comment.