Introduce new, Hugo templates based, website (#713)
* Add new hugo-based website for hawkBit Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Fix broken links + wordings - , i.e. -> i.e, - , e.g. -> e.g., - hawkbit -> hawkBit - don't -> do not - isn't -> is not Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Remove old documentation and add maven integration Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Add Intellij files to ignore Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Update README Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Update Copyright header * exclude website artifacts Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Harmonize usage of i.e. and e.g. Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Add remark for windows user Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Fix indention Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Introduce review findings Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com> * Change image in 'run hawkbit' guide Signed-off-by: Jeroen Laverman <jeroen.laverman@bosch-si.com>
This commit is contained in:
Jeroen Laverman
committed by
Dominic Schabel
Dominic Schabel
parent
fa751c397b
commit
f96876afe0
73
docs/content/concepts/authentication.md
Normal file
73
docs/content/concepts/authentication.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Authentication
|
||||
parent: Concepts
|
||||
weight: 51
|
||||
---
|
||||
|
||||
A hawkBit update server can be accessed in four different ways:
|
||||
|
||||
- _Direct Device Integration (DDI) API_ by **targets**.
|
||||
- _Management API_ by 3rd party **applications**.
|
||||
- _Device Management Federation (DMF) API_ by 3rd party **applications** through AMQP.
|
||||
- _Management UI_ by **users**.
|
||||
<!--more-->
|
||||
|
||||
|
||||
## DDI API Authentication Modes
|
||||
|
||||
### Security Token
|
||||
|
||||
hawkBit supports multiple ways to authenticate a target against the server. The different authentication modes can be individual enabled and disabled within hawkBit. Both on system level (with Spring Boot properties) as per individual tenant.
|
||||
|
||||
#### Target Security Token Authentication
|
||||
There is a 32 alphanumeric character security-token for each created target within IoT hawkBit. This token can be used to authenticate the target at hawkBit through the HTTP-Authorization header with the custom scheme _TargetToken_.
|
||||
|
||||
```
|
||||
GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
|
||||
Host: your.hawkBit.server
|
||||
Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY
|
||||
```
|
||||
|
||||
The target security token is provided in [DMF API](../../apis/dmf_api/) as part of the update message in order to allow DMF clients to leverage the feature or can it be manually retrieved per target by [Management API](../../apis/management_api/) or in the [Management UI](../../ui) in the target details.
|
||||
|
||||
Note: needs to be enabled in your hawkBit installation **and** in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See [DdiSecurityProperties](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java) for system wide enablement.
|
||||
|
||||
The additional activation for the individual tenant:
|
||||
|
||||
|
||||
|
||||
#### Gateway Security Token Authentication
|
||||
Often the targets are connected through a gateway which manages the targets directly and as a result are indirectly connected to the hawkBit update server.
|
||||
|
||||
To authenticate this gateway and allow it to manage all target instances under its tenant there is a _GatewayToken_ to authenticate this gateway through the HTTP-Authorization header with a custom scheme _GatewayToken_. This is of course also handy during development or for testing purposes. However, we generally recommend to use this token with care as it allows to act _in the name of_ any device.
|
||||
|
||||
```
|
||||
GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
|
||||
Host: your.hawkBit.server
|
||||
Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW
|
||||
```
|
||||
|
||||
Note: needs to be enabled in your hawkBit installation **and** in the tenant configuration. That allows both the operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method. See [DdiSecurityProperties](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java) for system wide enablement.
|
||||
|
||||
The additional activation for the individual tenant:
|
||||
|
||||
|
||||
|
||||
#### Anonymous access
|
||||
Here we offer general anonymous access for all targets (see [DdiSecurityProperties](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java)) which we consider not really sufficient for a production system but it might come in handy to get a project started in the beginning.
|
||||
|
||||
However, anonymous download on the other side might be interesting even in production for scenarios where the artifact itself is already encrypted.
|
||||
|
||||
The activation for the individual tenant:
|
||||
|
||||
|
||||
|
||||
## DMF API
|
||||
Authentication is provided by _RabbitMQ_ [vhost and user credentials](https://www.rabbitmq.com/access-control.html) that is used for the integration.
|
||||
|
||||
## Management API
|
||||
- Basic Auth
|
||||
|
||||
## Management UI
|
||||
- Login Dialog
|
||||
|
||||
62
docs/content/concepts/authorization.md
Normal file
62
docs/content/concepts/authorization.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Authorization
|
||||
parent: Concepts
|
||||
weight: 52
|
||||
---
|
||||
|
||||
Authorization is handled separately for _Direct Device Integration (DDI) API_ and _Device Management Federation (DMF) API_ (where successful authentication includes full authorization) and _Management API_ and _UI_ which is based on Spring security [authorities](https://github.com/eclipse/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/im/authentication/SpPermission.java).
|
||||
<!--more-->
|
||||
|
||||
However, keep in mind that hawkBit does not offer an off the shelf authentication provider to leverage these permissions and the underlying multi user/tenant capabilities of hawkBit. Check out [Spring security documentation](http://projects.spring.io/spring-security/) for further information. In hawkBit [SecurityAutoConfiguration](https://github.com/eclipse/hawkbit/blob/master/hawkbit-autoconfigure/src/main/java/org/eclipse/hawkbit/autoconfigure/security/SecurityAutoConfiguration.java) is a good starting point for integration.
|
||||
|
||||
The default implementation is single user/tenant with basic auth and the logged in user is provided with all permissions.
|
||||
|
||||
## DDI API
|
||||
An authenticated target is permitted to:
|
||||
- retrieve commands from the server
|
||||
- provide feedback to the the server
|
||||
- download artifacts that are assigned to it
|
||||
|
||||
A target might be permitted to download artifacts without authentication (if enabled, see above). Only the download can be permitted to disable the authentication. This can be used in scenarios where the artifacts itself are e.g. signed and secured.
|
||||
|
||||
## Management API and UI
|
||||
|
||||
### Delivered Permissions
|
||||
- READ_/UPDATE_/CREATE_/DELETE_TARGETS for:
|
||||
- Target entities including metadata (that includes also the installed and assigned distribution sets)
|
||||
- Target tags
|
||||
- Target actions
|
||||
- Target registration rules
|
||||
- Bulk operations
|
||||
- Target filters
|
||||
|
||||
- READ_/UPDATE_/CREATE_/DELETE_REPOSITORY for:
|
||||
- Distribution sets
|
||||
- Software Modules
|
||||
- Artifacts
|
||||
- DS tags
|
||||
|
||||
- READ_TARGET_SECURITY_TOKEN
|
||||
- Permission to read the target security token. The security token is security concerned and should be protected.
|
||||
|
||||
- DOWNLOAD_REPOSITORY_ARTIFACT
|
||||
- Permission to download artifacts of an software module (Note: READ_REPOSITORY allows only to read the metadata).
|
||||
|
||||
- TENANT_CONFIGURATION
|
||||
- Permission to administrate the tenant settings.
|
||||
|
||||
- ROLLOUT_MANAGEMENT
|
||||
- Permission to provision targets through rollouts.
|
||||
|
||||
### Permission Matrix for example uses cases that need more than one permission
|
||||
|
||||
Use Case | Needed permissions
|
||||
-------------------------------------------------------------------------- | --------------------------------------------------
|
||||
Search _targets_ by installed or assigned _distribution set_ | READ_TARGET, READ_REPOSITORY
|
||||
Assign _DS_ to a _target_ | READ_REPOSITORY, UPDATE_TARGET
|
||||
Assign DS to target through a _Rollout_, i.e. _Rollout_ creation and start | READ_REPOSITORY, UPDATE_TARGET, ROLLOUT_MANAGEMENT
|
||||
Read _Rollout_ status including its _deployment groups_ | ROLLOUT_MANAGEMENT
|
||||
Checks _targets_ inside _Rollout deployment group_ | READ_TARGET, ROLLOUT_MANAGEMENT
|
||||
|
||||
## Device Management Federation API
|
||||
The provided _RabbitMQ_ [vhost and user](https://www.rabbitmq.com/access-control.html) should be provided with the necessary permissions to send messages to hawkBit through the exchange and receive messages from it through the specified queue.
|
||||
49
docs/content/concepts/datamodel.md
Normal file
49
docs/content/concepts/datamodel.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Data Model
|
||||
parent: Concepts
|
||||
weight: 53
|
||||
---
|
||||
|
||||
The hawkBit data model was designed to have enough flexibility to define complex software structures (e.g. operating system, runtimes, apps, different kind of artifacts) on one side and simplicity compared to the capabilities of a full blown configuration management on the other.
|
||||
<!--more-->
|
||||
|
||||
It does define a hierarchy of software that starts with a distribution, which can have (sub-)modules and these may have multiple artifacts. However, it does not consider any kind of dependency definitions between modules or artifacts. As a result dependency checks if necessary have to be done outside hawkBit, i.e. on the device itself or before the entity creation in hawkBit by the origin.
|
||||
|
||||
## Provisioning Target Definition
|
||||
|
||||
A Provisioning Target is a neutral definition that may be an actual real device (e.g. gateway, embedded sensor) or a virtual device (e.g. vehicle, smart home).
|
||||
|
||||
The definition in hawkBit might reflect the transactional behavior if necessary on the device side. A vehicle might be updated device by device or as a whole. As a result one way of defining a vehicle in hawkBit could be to have one all inclusive Software Module or one module per (sub-) device.
|
||||
|
||||
## Software Structure Definition
|
||||
|
||||
The structure defines the model of the supported software by the provisioning target
|
||||
|
||||
Distribution Set Type: defines a package structure that is supported by certain devices
|
||||
Consists of Software Module Types both for
|
||||
Firmware - device can have only one module of that type (e.g. the operating system)
|
||||
Software - device can have multiple modules of that type (e.g. "Apps")
|
||||
Software Content Definition
|
||||
|
||||
Distribution Set: can be deployed to a provisioning target
|
||||
Software Module: is a sub element of the distribution
|
||||
e.g. OS, application, firmware X, firmware Y
|
||||
Artifact: binaries for a software module. Note: the decision which artifacts have to be downloaded are done on the device side.
|
||||
e.g. Full package, signatures, binary deltas
|
||||
|
||||
|
||||
## Entity Relationships
|
||||
The public defined entities and their relation which are reflected by the Management API.
|
||||
|
||||
|
||||
|
||||
## Deleting and Archiving Software Modules
|
||||
When a user deletes a Software Module, the update server cannot simply remove all the corresponding data. Because when the Software Module is already assigned to a Distribution Set or was assigned to a Target in the past, the hawkBit server has to make sure that remains a clean and full update history for every target. The history contains all information (e.g. name, version) of the software, which was assigned to a specific Target. Obviously storing the binary data of the artifacts is not necessary for the history purpose.
|
||||
|
||||
The delete process which is performed, when there are historical connections to targets is called SoftDelete. This process marks the Software Module as deleted and removes the artifact, but it won't delete the meta data, which describes the SoftwareModule and the associated Artifacts. SoftwareModules, which are marked as delete won't be visible for the user, when he is requesting all SoftwareModules.
|
||||
|
||||
Just in case there are no connections to Distribution Sets and targets the server will perform a HardDelete. This process deletes all stored data, including all meta information.
|
||||
|
||||
{{% note %}}
|
||||
In case of of a SoftDelete the unique constraints are still in place, i.e. you cannot create an entity with the same name/key. This constraint might be removed in future versions because of the impact on the user experience (i.e. he does not see the soft deleted module but cannot create a new one).
|
||||
{{% /note %}}
|
||||
49
docs/content/concepts/rollout-management.md
Normal file
49
docs/content/concepts/rollout-management.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Rollout Management
|
||||
parent: Concepts
|
||||
weight: 54
|
||||
---
|
||||
|
||||
Software update operations in large scale IoT scenarios with hundreds of thousands of devices require special handling.
|
||||
<!--more-->
|
||||
|
||||
That includes:
|
||||
- _Technical Scalability_ by means of horizontal scale of the hawkBit server cluster in the cloud.
|
||||
- _Global_ artifact _content delivery_ capacities.
|
||||
- _Functional Scalability_ by means of:
|
||||
- Secure handling of large volumes of devices at rollout creation time.
|
||||
- Monitoring of the rollout progress.
|
||||
- Emergency rollout shutdown in case of problems on to many devices.
|
||||
|
||||
- Reporting capabilities for a complete understanding of the rollout progress at each point in time.
|
||||
|
||||
Eclipse hawkBit sees these capabilities under the term Rollout Management.
|
||||
|
||||
The following capabilities are currently supported by the _Rollout Management_:
|
||||
- Create, update and start of rollouts.
|
||||
- Selection of targets as input for the rollout based on _target filter_ functionality.
|
||||
- Selection of a _DistributionSet_.
|
||||
- Auto-splitting of the input target list into a defined number deployment groups.
|
||||
- Approval workflow
|
||||
- Has to be enabled explicitly in configuration.
|
||||
- Enables a workflow that requires a user with adequate permissions to review any new or updated rollout before it
|
||||
can be started.
|
||||
- Allows integration with 3rd party workflow engines.
|
||||
|
||||
- Cascading start of the deployment groups based on installation status of the previous group.
|
||||
- Emergency shutdown of the rollout in case a group exceeds the defined error threshold.
|
||||
- Rollout progress monitoring for the entire rollout and the individual groups.
|
||||
|
||||
|
||||
## Cascading Deployment Group Execution
|
||||
The cascading execution of the deployment groups is based on two thresholds that can be defined by the rollout creator.
|
||||
- success condition by means of percentage of successfully installed targets in the current groups triggers.
|
||||
- error condition by means of absolute or percentage of failed installations which triggers an emergency shutdown of the entire rollout.
|
||||
|
||||
## Rollout state machine
|
||||
|
||||
### State Machine on Rollout
|
||||
|
||||
|
||||
### State Machine on Rollout Deployment Group
|
||||
|
||||
21
docs/content/concepts/targetstate.md
Normal file
21
docs/content/concepts/targetstate.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Target State Machine
|
||||
parent: Concepts
|
||||
weight: 55
|
||||
---
|
||||
|
||||
A target has a current state which reflects the provisioning status of the device at this point in time. State changes are driven either by the update server by means of starting an update or by the controller on the provisioning target that gives feedback to the update server, e.g. "I am here", "I am working on a provisioning", "I have finished a provisioning".
|
||||
<!--more-->
|
||||
|
||||
## Defined states
|
||||
|
||||
State | Description
|
||||
---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||||
UNKNOWN | Set by default for a pre-commissioned target until first status update received from the target. Is the initial starting point for targets created by UI or management API.
|
||||
IN_SYNC | Assigned _Distribution Set_ is installed.
|
||||
PENDING | Installation of assigned _Distribution Set_ is not yet confirmed.
|
||||
ERROR | Installation of assigned _Distribution Set_ has failed.
|
||||
REGISTERED | Target registered at the update server but no _Distribution Set_ assigned. Is the initial starting point for plug-and-play devices.
|
||||
|
||||
## Transitions
|
||||
|
||||
Reference in New Issue
Block a user