diff --git a/docs/README.md b/docs/README.md index dea2ade9b..6e1019900 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,43 +3,48 @@ Eclipse hawkBit™ is a domain independent back-end framework for rolling out software updates to constrained edge devices as well as more powerful controllers and gateways connected to IP based networking infrastructure.

- eclipse foundation logo + Eclipse hawkBit Overview

--- ## Interfaces -hawkBit offers a direct device integration via HTTP or a device management federation API which allows to connect devices with different protocol adapter. Users can make use of the graphical user interface and other service can interact with hawkBit through the RESTful management API. +Eclipse hawkBit™ provides three APIs, each designed to support specific integration requirements for device connectivity, device management, and external service federation. + +### Management API + +The Management API is a RESTful interface that allows Create, Read, Update, and Delete (CRUD) operations for provisioning targets (e.g., devices) and repository content (e.g., software). Using the Management API, you can manage and monitor software update processes. It supports JSON payloads with Hypermedia and offers filtering, sorting, and pagination capabilities + +The following sections provide a high-level overview. For in-depth information, including request flows and examples, see the [Management API documentation](#management-api) + +### Direct Device Integration (DDI) API + +The Direct Device Integration (DDI) API is built on HTTP standards and uses a polling-based approach. + +Eclipse hawkBit™ exposes RESTful resources that devices consume to retrieve software update tasks, including artifact partial and resume downloads (RFC7233), and to report back status and feedback. + +The DDI API supports ETag-based traffic optimization, allowing devices to efficiently check for updates without unnecessary data transfer. + +Learn more in the [DDI API documentation](direct-device-integration-api.md) + +### Device Management Federation (DMF) API + +The Device Management Federation (DMF) API enables indirect device integration via a device management service into hawkBit. It is a message-based, asynchronous API optimized for high-throughput cloud service-to-service communication. The DMF API leverages RabbitMQ messaging and provides strong tenant isolation through dedicated AMQP virtual hosts per tenant. + +For a detailed description and usage examples, see the [Device Management Federation (DMF) API documentation](device-management-federation-api.md) --- -## Rollout +## Device Repository -
- -
- -hawkBit supports an easy and flexible rollout management which allows you to update a large amount of devices in separated groups. - -- 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. - -
- -
- -Rollout Diagram - -
- -
- ---- - -## Package Model +- **Device State Storage**: The Device Repository manages connected devices (targets) and their state. It allows you to retrieve device details and attributes, maintain descriptions, metadata, tags, and track assigned and installed software versions, including software update status. +- **Tagging**: hawkBit™ allows creating and managing arbitrary tags that can be assigned to devices. These tags become part of the target metadata and can be used as a simple, flexible way to filter and group devices in both the UI and API +- **Filtering and Grouping**: Advanced device management is enabled through Target Filters, which group devices based on query criteria. These filters not only simplify device organization but also support automatic update assignments - for example, newly registered devices that match a filter are automatically assigned the corresponding software update. +## Software Repository +#### Distribution Sets and Software Modules +The software repository organizes and manages software updates. A software update, called a Distribution Set, is composed of one or more Software Modules, each containing multiple artifacts.
@@ -50,9 +55,78 @@ hawkBit supports an easy and flexible rollout management which allows you to upd
-A software update does not always contain only a single file. -The hawkBit meta model allows you to configure your files in virtual software and distribution packages. +**Structure**: +- **Distribution Set**: Complete software package for deployment + - Version controlled + - Can contain multiple software modules + - Distribution set types (OS, Application, Firmware, etc.) +- **Software Module**: Individual software component + - Contains one or more artifacts (files) + - Software module types (customizable) + - Mandatory vs. optional designation +- **Artifact**: Binary files with metadata + - Multiple hash algorithms (MD5, SHA1, SHA256) + - Encryption support + - Signature support
+ +Metadata can be assigned to both Software Modules and Distribution Sets. + +#### Tagging and Filtering +hawkBit™ lets you assign user‑defined tags to Distribution Sets and then filter Distribution Sets using those tags, making it easier to organize and locate updates based on custom criteria. + +#### Locking After Assignment + +To ensure consistency and prevent unintended changes, hawkBit™ supports locking of Distribution Sets after they have been assigned to a target (device or group). When a distribution set is locked, all its software modules are automatically locked, and they cannot be modified until they are unlocked. This provides stability for ongoing deployments, ensuring that the software being rolled out remains consistent throughout the deployment process. + + +#### Required Migration Step Flag + +When creating a Distribution Set, you can set a flag to indicate that applying this update requires a migration step on the device. This is useful for ensuring data migration, configuration changes, or other necessary steps are performed during the update process to ensure a successful transition. + +## Artifact Content Delivery + +The Artifact Content Delivery component manages the storage and delivery of software artifacts to devices. It supports partial and resumable downloads using RFC7233 range requests, allowing devices to efficiently retrieve large files even in unreliable network conditions. The content management is accessible via RESTful APIs and the UI, with authorization based on software assignment to ensure that devices can only download artifacts they are authorized for. + +## Rollout Management + +Rollout Management in Eclipse hawkBit™ is a core feature designed to orchestrate and control the deployment of software updates to large fleets of devices in a safe, flexible, and automated way. + +It enables group-based deployments with configurable success and error thresholds. Groups can cascade based on the status of previous groups. + +Rollout Diagram + +The traditional “big bang” approach updates all devices at once, creating a sharp load spike and risking infrastructure overload, while hawkBit’s phased rollout spreads updates across smaller groups over time, smoothing load and maintaining system stability. + +Rollout Diagram + +Rollouts can be started, paused, resumed, stopped, or retried, with real-time monitoring and emergency stop features. +Devices can be added dynamically, and detailed status tracking is available for each rollout stage. + +To explore software update in greater detail, visit [Rollout Management documentation](rollout-management.md) + +## Reporting and Monitoring + +Eclipse hawkBit™ provides real-time visibility and historical insight into how software updates are rolled out, executed, and completed across large device fleets. Reporting and monitoring are tightly coupled to its rollout and device management model. + +#### Monitoring Features +- **Rollout Progress Tracking**: Monitor deployment stages, group completion, and cascading group triggers +- **Action States**: Track individual device update actions (pending, running, finished, error, canceled) +- **Action History**: Monitor the status of every device via its action history. This action history makes transparent which action happened at which particular time and with its result. +- **Success/Error Thresholds**: Configure and monitor threshold violations that can pause or stop rollouts +- **Device Connectivity**: Track device polling activity, last seen timestamps, and overdue detection +- **Download Progress**: Monitor artifact download status and completion rates + +#### Reporting Channels +- **Management API**: RESTful endpoints for querying device status, action history, and rollout metrics +- **Event System**: Publish events for entity changes, action status updates, target polling, and download progress +- **RabbitMQ Events**: Remote events for distributed monitoring and integration with external tools + +## Authentication & Security + +Eclipse hawkBit™ provides comprehensive authentication and security features to protect devices, management interfaces, and data. All communication is protected using TLS/HTTPS, and update delivery is restricted to authenticated devices. hawkBit also records deployment and action history for traceability and auditing. While it keeps built-in security mechanisms focused and lightweight, hawkBit is designed to integrate easily with external identity, logging, and security systems for production use. + +If you’d like to explore security controls in more detail, check out the [Authentication](authentication.md) and [Authorization](authorization.md) documentation. \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 835cdcb3e..2ff58443e 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,9 +1,9 @@ -- Getting Started - - [Overview](README.md) +- Introduction - [What is hawkBit](what-is-hawkbit.md) + - [Overview](README.md) +- Getting Started - [Quick Start](quick-start.md) - - [Features](features.md) - - [Architecture](architecture.md) + - [Device Provisioning](device-provisioning.md) - Guides - [Base Setup](base-setup.md) @@ -11,12 +11,14 @@ - [Feign Client](feign-client.md) - [Clustering](clustering.md) --Concepts +- Concepts + - [Architecture](architecture.md) - [Authentication](authentication.md) - [Authorization](authorization.md) - [Data model](datamodel.md) - [Rollout management](rollout-management.md) - [Targets state](targetstate.md) + - [Entity definitions](entity-definitions.md) - APIs - [Management API](management-api.md) diff --git a/docs/device-provisioning.md b/docs/device-provisioning.md new file mode 100644 index 000000000..e1a1bef02 --- /dev/null +++ b/docs/device-provisioning.md @@ -0,0 +1,505 @@ +# Device Provisioning + +Device provisioning is the process of registering a device with the hawkBit update server so it can receive software updates. hawkBit supports two main provisioning scenarios: +- **Provisioning and Registration via Management API**: An administrator or backend system register devices in hawkBit before they connect by providing device identification and description. This approach provides centralized control and is ideal for pre-planned deployments. +- **Direct Registration via DDI API**: Devices register themselves automatically when they first connect to hawkBit. This is called auto-registration and is ideal for dynamic environments. + +## Provisioning and Registration via Management API + +In this scenario, an administrator or backend system first provision the device using the Management UI or the [Management API](management-api.md). This is the step where the device identification and description is provided. + +### When to Use + +- Devices are provisioned during manufacturing or warehouse setup +- You need to assign software updates before devices are deployed +- You require strict inventory control +- You want to pre-configure security tokens +- Bulk provisioning of many devices + +### Prerequisites + +- Management API access with appropriate permissions: + - `CREATE_TARGET` - to create targets + - `UPDATE_TARGET` - to modify targets + - `READ_TARGET` - to view targets +- Valid credentials (username/password) for Basic Authentication +- Target Security Token authentication enabled on the server - see [Configuration Properties](#configuration-properties) below + +### Workflow +```mermaid + %%{init: {'theme':'base', 'themeVariables': { + 'primaryColor':'#6BAF4A', + 'primaryTextColor':'#000', + 'primaryBorderColor':'#6BAF4A', + 'lineColor':'#4A2C5C', + 'secondaryColor':'#E8D5F2', + 'tertiaryColor':'#6BAF4A', + 'noteBkgColor':'#F5F5F5', + 'noteTextColor':'#000', + 'noteBorderColor':'#6BAF4A', + 'actorBorder':'#4A2C5C', + 'actorBkg':'#6BAF4A', + 'actorTextColor':'#000', + 'actorLineColor':'#4A2C5C', + 'signalColor':'#4A2C5C', + 'signalTextColor':'#000', + 'labelBoxBkgColor':'#E8D5F2', + 'labelBoxBorderColor':'#6BAF4A', + 'labelTextColor':'#000', + 'loopTextColor':'#000', + 'activationBorderColor':'#4A2C5C', + 'activationBkgColor':'#F5F5F5', + 'sequenceNumberColor':'#FFF' + }}}%% +sequenceDiagram + participant Admin as Admin/Backend System + participant MgmtAPI as Management API
(REST) + participant Server as hawkBit Server + participant DDIAPI as DDI API
(REST) + participant Device as Device + + Note over Admin,Device: Phase 1: Provisioning (Before Device Deployment) + + Admin->>MgmtAPI: POST /rest/v1/targets + Note right of Admin: Create device with:
- controllerId
- name, description
- securityToken (optional)
- requestAttributes + activate MgmtAPI + MgmtAPI->>Server: Create Target Entity + activate Server + Server->>Server: Generate securityToken
(if not provided) + Server->>Server: Set updateStatus:
"registered" + Server-->>MgmtAPI: 201 Created + deactivate Server + MgmtAPI-->>Admin: Target created with
securityToken + deactivate MgmtAPI + + Note over Admin,Device: Phase 2: Device Registration (First Connection) + + Device->>DDIAPI: GET /{tenant}/controller/v1/{controllerId} + Note right of DDIAPI: Authorization:
TargetToken {securityToken} + activate DDIAPI + DDIAPI->>Server: Authenticate & Retrieve Target + activate Server + Server->>Server: Validate securityToken
Update lastControllerRequestAt + Server-->>DDIAPI: Target Configuration + deactivate Server + DDIAPI-->>Device: 200 OK
Polling interval + links + deactivate DDIAPI + Note left of Device: config.polling.sleep
_links.configData + + Note over Admin,Device: Phase 3: Add Device Attributes (Optional) + + Device->>DDIAPI: PUT /{tenant}/controller/v1/{controllerId}/configData + Note right of DDIAPI: Send attributes:
- hwRevision
- VIN
- OS version
mode: "merge" + activate DDIAPI + DDIAPI->>Server: Update Target Attributes + activate Server + Server->>Server: Merge/Replace/Remove
attributes + Server-->>DDIAPI: 200 OK + deactivate Server + DDIAPI-->>Device: Configuration updated + deactivate DDIAPI +``` +### Provisioning + +**Endpoint:** +``` +POST /rest/v1/targets +``` + +**Request Headers:** +```http +Content-Type: application/json +Authorization: Basic +``` + +**Request Body:** +```json +[ + { + "controllerId": "device-12345", + "name": "Production Device 12345", + "description": "Temperature sensor - Building A", + "address": "https://192.168.1.100", + "securityToken": "myCustomToken123456", + "requestAttributes": true, + "targetType": 1 + } +] +``` +See [Target Entity Definition](entity-definitions.md#target) for all available fields. + +**Response:** 201 Created +```json +[ + { + "createdBy": "admin", + "createdAt": 1709212800000, + "lastModifiedBy": "admin", + "lastModifiedAt": 1709212800000, + "controllerId": "device-12345", + "name": "Production Device 12345", + "description": "Temperature sensor - Building A", + "updateStatus": "registered", + "securityToken": "mySecureToken987654321", + "address": "https://192.168.1.100", + "lastControllerRequestAt": 0, + "installedAt": 0, + "_links": { + "self": { + "href": "http://localhost:8080/rest/v1/targets/device-12345" + }, + "assignedDS": { + "href": "http://localhost:8080/rest/v1/targets/device-12345/assignedDS" + }, + "installedDS": { + "href": "http://localhost:8080/rest/v1/targets/device-12345/installedDS" + }, + "attributes": { + "href": "http://localhost:8080/rest/v1/targets/device-12345/attributes" + }, + "actions": { + "href": "http://localhost:8080/rest/v1/targets/device-12345/actions" + } + } + } +] +``` + +### Registration +To complete the whole process, the provisioned device can register itself via the [Direct Device Integration API](direct-device-integration-api.md) using its `controllerId` and `securityToken`. + +**Endpoint:** +``` +GET /{tenant}/controller/v1/{controllerId} +``` + +**Request Headers:** +```http +Authorization: TargetToken mySecureToken987654321 +``` + +**Response:** 200 OK +```json +{ + "config": { + "polling": { + "sleep": "00:05:00" + } + }, + "_links": { + "configData": { + "href": "http://localhost:8080/DEFAULT/controller/v1/device-12345/configData" + } + } +} +``` + +### Add Device Attributes (Optional) + +By following the link to `configData` provided in response to the last call, you can add some attributes to the device. In the code example below, we have shown how to add two attributes, namely hwRevision and VIN. + +**Endpoint:** `PUT {tenant}/controller/v1/{controllerId}/configData` + +**Authentication:** TargetToken + +**Request Headers:** +```http +Content-Type: application/json +Authorization: TargetToken mySecureToken987654321 +``` + +**Request Body:** +```json +{ + "mode": "merge", + "data": { + "hwRevision": "2", + "VIN": "JH4TB2H26CC000000" + } +} +``` + +**Response:** 200 OK +```json +``` + +### Best Practices + +1. **Security Tokens**: Generate strong, unique tokens for each device (at least 32 characters) +2. **Bulk Creation**: Use array notation to create multiple targets in a single request +3. **Target Types**: Use target types to categorize devices (e.g., by hardware model) +4. **Naming Convention**: Use consistent, meaningful naming for `controllerId` (e.g., serial numbers) +5. **Pre-assignment**: Assign distribution sets before devices go online for immediate updates + +--- + +## Direct Registration via Direct Device Integration API + +In this scenario, devices register themselves automatically when they first connect to hawkBit. This is called **auto-registration** and is ideal for dynamic environments. + +### When to Use +- Devices are manufactured without pre-registration +- You have a dynamic fleet with frequent additions +- Gateway devices manage multiple sub-devices +- You prefer decentralized, self-service provisioning +- IoT scenarios with thousands of devices + +### Prerequisites +- Gateway Token authentication enabled on the server: + - Target Security Token mode (per-device tokens), OR + - Gateway Token mode (single token for all devices in a tenant), OR + - Certificate-based authentication (mTLS) +- Device must know its `controllerId` (typically MAC address, serial number, or UUID) + +see [Configuration Properties](#configuration-properties) below for details on how to enable authentication modes. + +### Workflow +```mermaid + %%{init: {'theme':'base', 'themeVariables': { + 'primaryColor':'#6BAF4A', + 'primaryTextColor':'#000', + 'primaryBorderColor':'#6BAF4A', + 'lineColor':'#4A2C5C', + 'secondaryColor':'#E8D5F2', + 'tertiaryColor':'#6BAF4A', + 'noteBkgColor':'#F5F5F5', + 'noteTextColor':'#000', + 'noteBorderColor':'#6BAF4A', + 'actorBorder':'#4A2C5C', + 'actorBkg':'#6BAF4A', + 'actorTextColor':'#000', + 'actorLineColor':'#4A2C5C', + 'signalColor':'#4A2C5C', + 'signalTextColor':'#000', + 'labelBoxBkgColor':'#E8D5F2', + 'labelBoxBorderColor':'#6BAF4A', + 'labelTextColor':'#000', + 'loopTextColor':'#000', + 'activationBorderColor':'#4A2C5C', + 'activationBkgColor':'#F5F5F5', + 'sequenceNumberColor':'#FFF' + }}}%% +sequenceDiagram + participant Device as Device + participant DDIAPI as DDI API
(REST) + participant Server as hawkBit Server + participant MgmtAPI as Management API
(REST) + participant Admin as Admin/Backend System + + Note over Device,Admin: Phase 1: Enable Gateway Token Authentication + + Admin->>MgmtAPI: GET /rest/v1/system/configs/authentication.gatewaytoken.key + Note right of MgmtAPI: Basic Auth:
admin credentials + activate MgmtAPI + MgmtAPI->>Server: Retrieve Gateway Token + activate Server + Server-->>MgmtAPI: Gateway Token Value + deactivate Server + MgmtAPI-->>Admin: Gateway Token:
3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW + deactivate MgmtAPI + + Note over Device,Admin: Phase 2: Device Auto-Registration (First Connection) + + Device->>DDIAPI: GET /{tenant}/controller/v1/{controllerId} + Note right of DDIAPI: Authorization:
GatewayToken {token} + activate DDIAPI + DDIAPI->>Server: Authenticate & Check Target + activate Server + Server->>Server: Target not found + Server->>Server: Auto-create Target:
- controllerId
- updateStatus: "registered"
- createdBy: "system" + Server->>Server: Generate securityToken
Update lastControllerRequestAt + Server-->>DDIAPI: Target Configuration + deactivate Server + DDIAPI-->>Device: 200 OK
Polling interval + links + deactivate DDIAPI + Note left of DDIAPI: config.polling.sleep
_links.configData + + Note over Device,Admin: Phase 3: Add Device Attributes (Optional) + + Device->>DDIAPI: PUT /{tenant}/controller/v1/{controllerId}/configData + Note right of DDIAPI: Send attributes:
- hw_revision
- os_version
- serial_number
mode: "merge" + activate DDIAPI + DDIAPI->>Server: Update Target Attributes + activate Server + Server->>Server: Merge/Replace/Remove
attributes + Server-->>DDIAPI: 200 OK + deactivate Server + DDIAPI-->>Device: Configuration updated + deactivate DDIAPI +``` + +### Enable Gateway Token Authentication + +All devices share a single token for the tenant. **Use with caution in production.** + +**Enable in system configuration:** +```properties +hawkbit.server.ddi.security.authentication.gatewaytoken.enabled=true +``` + +**Enable in tenant configuration:** +``` +authentication.gatewaytoken.enabled=true +``` + +**Retrieve Gateway Token:** +```bash +curl http://localhost:8080/rest/v1/system/configs/authentication.gatewaytoken.key \ + -u admin:admin +``` + +**Response:** +```json +{ + "value": "3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW", + "global": false, + "lastModifiedAt": 1770794878411, + "lastModifiedBy": "admin", + "createdAt": 1770794562205, + "createdBy": "admin", + "_links": { + "self": { + "href": "http://localhost:8080/rest/v1/system/configs/authentication.gatewaytoken.key" + } + } +} +``` + +### Device Auto-Registration on First Poll + +The device polls the hawkBit server using its `controllerId`. If the target doesn't exist, hawkBit creates it automatically. + +**Endpoint:** +``` +GET /{tenant}/controller/v1/{controllerId} +``` +**Authentication:** GatewayToken + +**Request Headers:** +```http +Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW +``` + +**Response:** 200 OK +```json +{ + "config": { + "polling": { + "sleep": "00:05:00" + } + }, + "_links": { + "configData": { + "href": "http://localhost:8080/DEFAULT/controller/v1/device-abc-001/configData" + } + } +} +``` + +### Add Device Attributes (Optional) + +The device can send its attributes (hardware version, OS version, custom data) to hawkBit. + +**Endpoint:** `PUT {tenant}/controller/v1/{controllerId}/configData` + +**Authentication:** GatewayToken + +**Request Headers:** +```http +Content-Type: application/json +Authorization: GatewayToken mySecureToken987654321 +``` + +**Request Body:** +```json +{ + "mode": "merge", + "data": { + "hw_revision": "1.2", + "os_version": "Linux 5.10.0", + "serial_number": "SN123456789", + "mac_address": "00:1A:2B:3C:4D:5E" + } +} +``` +**Modes:** +- `merge`: Merge new attributes with existing ones +- `replace`: Replace all attributes with new data +- `remove`: Remove specified attributes + +**Response:** 200 OK +```json +``` + +### Best Practices + +1. **Authentication**: Use Target Security Tokens or certificates in production; Gateway Tokens only for development +2. **Polling Interval**: Respect the server-provided polling interval to avoid overloading the server +3. **Attributes**: Send detailed device attributes to enable filtering and reporting +4. **Controller ID**: Use persistent, unique identifiers (MAC address, serial number, UUID) +5. **Feedback**: Always send feedback after updates (success/failure) for audit trails +6. **Error Handling**: Implement exponential backoff on connection failures + +--- + +## Comparison: Management API vs DDI API + +| Aspect | Management API Provisioning | DDI Auto-Registration | +|--------|----------------------------|----------------------| +| **Timing** | Before device deployment | On first device connection | +| **Control** | Centralized by admin | Decentralized (device-initiated) | +| **Use Case** | Pre-planned deployments | Dynamic fleet management | +| **Authentication** | Basic Auth (admin credentials) | TargetToken / GatewayToken / mTLS | +| **Security Token** | Set during creation or auto-generated | Auto-generated on registration | +| **Pre-assignment** | Possible before device connects | Only after first poll | +| **Scalability** | Manual or scripted bulk creation | Automatic, scales infinitely | +| **Device Attributes** | Must be set via separate request | Device sends on first connection | +| **Audit Trail** | `createdBy: admin` | `createdBy: system` | + +--- + +## Security Considerations + +### Management API + +1. **Access Control**: Restrict Management API access using role-based permissions +2. **Credentials**: Use strong passwords and consider API keys for automated systems +3. **HTTPS**: Always use HTTPS in production to protect credentials +4. **Token Generation**: Generate cryptographically random security tokens (32+ characters) +5. **Least Privilege**: Grant only necessary permissions (e.g., `CREATE_TARGET` for provisioning systems) + +### DDI API + +1. **Gateway Token**: Never use in production for large deployments; prefer per-device tokens +2. **Token Storage**: Devices should securely store their security tokens (TPM, secure element) +3. **Certificate Auth**: Use mTLS for maximum security in IoT deployments +4. **Token Rotation**: Consider implementing token rotation mechanisms +5. **Auto-Registration**: Disable auto-registration in highly secure environments; use Management API only + +--- + +## Configuration Properties + +### Enable DDI Authentication Modes + +**System-wide (application.properties):** +```properties +# Target Security Token (per-device) +hawkbit.server.ddi.security.authentication.targettoken.enabled=true + +# Gateway Token (shared token) +hawkbit.server.ddi.security.authentication.gatewaytoken.enabled=true + +# Anonymous downloads (not recommended for production) +hawkbit.server.ddi.security.authentication.anonymous.enabled=false +``` +--- +## Related Documentation + +- [Management API](management-api.md) - Complete Management API reference +- [Direct Device Integration API](direct-device-integration-api.md) - Complete DDI API reference +- [Authentication](authentication.md) - Detailed authentication mechanisms +- [Authorization](authorization.md) - Role-based access control +- [Entity Definitions](entity-definitions.md) - Data models and schemas + +--- \ No newline at end of file diff --git a/docs/entity-definitions.md b/docs/entity-definitions.md new file mode 100644 index 000000000..3f469b1b9 --- /dev/null +++ b/docs/entity-definitions.md @@ -0,0 +1,260 @@ +# Entity Definitions + +## Target + +Targets represent devices or software instances that can receive software updates. + +**Filterable/Sortable Fields:** + +| Field | Description | Type | +|------------------------------------|----------------------------------------------------------------------|------| +| `controllerId` | Unique identifier of the target | String | +| `name` | Display name | String | +| `description` | Description text | String | +| `updateStatus` | Current update status (UNKNOWN, IN_SYNC, PENDING, ERROR, REGISTERED) | Enum | +| `address` | IP address or URI | String | +| `lastTargetQuery` | Last time the target polled (timestamp in ms) | Long | +| `createdAt` | Creation timestamp | Long | +| `createdBy` | Creator username | String | +| `lastModifiedAt` | Last modification timestamp | Long | +| `lastModifiedBy` | Last modifier username | String | +| `assignedDistributionSet.name` | Name of assigned distribution set | String | +| `assignedDistributionSet.version` | Version of assigned distribution set | String | +| `installedDistributionSet.name` | Name of installed distribution set | String | +| `installedDistributionSet.version` | Version of installed distribution set | String | +| `targetType.key` | Target type key | String | +| `targetType.name` | Target type name | String | +| `tags.name` | Tag name | String | +| `group` | Group name | String | +| `metadata.` | Metadata value by key | String | +| `controllerAttributes.` | Controller attribute by key | String | + +**Example Queries:** +``` +# Find targets with update errors +updateStatus==ERROR + +# Find targets by name pattern +name==device-* + +# Find targets with specific distribution set assigned +assignedDistributionSet.name==Firmware;assignedDistributionSet.version==2.0.0 + +# Find targets that haven't polled in 24 hours (timestamp example) +lastTargetQuery=lt=1704067200000 + +# Find targets by tag +tags.name==production + +# Find targets by metadata +metadata.location==factory-A + +# Find targets by controller attribute +controllerAttributes.firmware_version==1.2.3 +``` + +--- + +## Distribution Set + +Distribution Sets are collections of software modules that can be deployed to targets. + +**Filterable/Sortable Fields:** + +| Field | Description | Type | +|-------|-------------|------| +| `id` | Unique identifier | Long | +| `name` | Distribution set name | String | +| `version` | Version string | String | +| `description` | Description text | String | +| `type.key` | Distribution set type key | String | +| `type.name` | Distribution set type name | String | +| `valid` | Whether the DS is valid for deployment | Boolean | +| `createdAt` | Creation timestamp | Long | +| `createdBy` | Creator username | String | +| `lastModifiedAt` | Last modification timestamp | Long | +| `lastModifiedBy` | Last modifier username | String | +| `tags.name` | Tag name | String | +| `modules.name` | Software module name | String | +| `metadata.` | Metadata value by key | String | + +**Example Queries:** +``` +# Find distribution sets by name +name==Firmware* + +# Find valid distribution sets only +valid==true + +# Find by type +type.key==os_app + +# Find by tag +tags.name==release-candidate + +# Find distribution sets containing a specific module +modules.name==bootloader +``` + +--- + +## Rollout + +Rollouts are used to deploy software to groups of targets in a controlled manner. + +**Filterable/Sortable Fields:** + +| Field | Description | Type | +|-------|-------------|------| +| `id` | Unique identifier | Long | +| `name` | Rollout name | String | +| `description` | Description text | String | +| `status` | Rollout status (CREATING, READY, PAUSED, STARTING, RUNNING, FINISHED, etc.) | Enum | +| `distributionSet.id` | Distribution set ID | Long | +| `distributionSet.name` | Distribution set name | String | +| `distributionSet.version` | Distribution set version | String | +| `distributionSet.type` | Distribution set type | String | +| `createdAt` | Creation timestamp | Long | +| `createdBy` | Creator username | String | +| `lastModifiedAt` | Last modification timestamp | Long | +| `lastModifiedBy` | Last modifier username | String | + +**Example Queries:** +``` +# Find running rollouts +status==RUNNING + +# Find rollouts by name +name==Campaign* + +# Find rollouts for a specific distribution set +distributionSet.name==Firmware;distributionSet.version==2.0.0 + +# Find finished or paused rollouts +status=in=(FINISHED,PAUSED) +``` + +--- + +## Action + +Actions represent deployment operations assigned to targets. + +**Filterable/Sortable Fields:** + +| Field | Description | Type | +|-------|-------------|------| +| `id` | Unique identifier | Long | +| `status` | Action status (SCHEDULED, RUNNING, FINISHED, ERROR, CANCELED, etc.) | Enum | +| `active` | Whether the action is currently active | Boolean | +| `weight` | Priority weight (0-1000) | Integer | +| `lastActionStatusCode` | Last status code reported | Integer | +| `externalRef` | External reference string | String | +| `target.controllerId` | Target controller ID | String | +| `target.name` | Target name | String | +| `target.updateStatus` | Target update status | Enum | +| `distributionSet.id` | Distribution set ID | Long | +| `distributionSet.name` | Distribution set name | String | +| `distributionSet.version` | Distribution set version | String | +| `rollout.id` | Rollout ID | Long | +| `rollout.name` | Rollout name | String | +| `rolloutGroup.id` | Rollout group ID | Long | +| `rolloutGroup.name` | Rollout group name | String | +| `createdAt` | Creation timestamp | Long | +| `createdBy` | Creator username | String | +| `lastModifiedAt` | Last modification timestamp | Long | +| `lastModifiedBy` | Last modifier username | String | + +**Example Queries:** +``` +# Find active actions +active==true + +# Find actions by status +status==RUNNING + +# Find failed actions +status==ERROR + +# Find actions for a specific target +target.controllerId==device-001 + +# Find actions for a specific rollout +rollout.name==Campaign2024 + +# Find high-priority actions +weight=gt=800 + +# Find actions with specific status code +lastActionStatusCode==200 +``` + +--- + +## Software Module + +Software Modules are individual software components that make up distribution sets. + +**Filterable/Sortable Fields:** + +| Field | Description | Type | +|-------|-------------|------| +| `id` | Unique identifier | Long | +| `name` | Module name | String | +| `version` | Version string | String | +| `description` | Description text | String | +| `type.key` | Software module type key | String | +| `type.name` | Software module type name | String | +| `createdAt` | Creation timestamp | Long | +| `createdBy` | Creator username | String | +| `lastModifiedAt` | Last modification timestamp | Long | +| `lastModifiedBy` | Last modifier username | String | +| `metadata.` | Metadata value by key | String | + +**Example Queries:** +``` +# Find modules by name +name==bootloader* + +# Find modules by type +type.key==os + +# Find modules by version +version==2.0.* + +# Find modules with specific metadata +metadata.checksum==abc123 +``` + +--- + +## Target Filter Query + +Target Filter Queries define RSQL filters for grouping targets, used for rollouts and auto-assignment. + +**Filterable/Sortable Fields:** + +| Field | Description | Type | +|-------|-------------|------| +| `id` | Unique identifier | Long | +| `name` | Filter name | String | +| `autoAssignDistributionSet.name` | Auto-assign DS name | String | +| `autoAssignDistributionSet.version` | Auto-assign DS version | String | +| `createdAt` | Creation timestamp | Long | +| `createdBy` | Creator username | String | +| `lastModifiedAt` | Last modification timestamp | Long | +| `lastModifiedBy` | Last modifier username | String | + +**Example Queries:** +``` +# Find filters by name +name==Production* + +# Find filters with auto-assignment configured +autoAssignDistributionSet.name==* + +# Find filters for a specific auto-assign distribution set +autoAssignDistributionSet.name==Firmware;autoAssignDistributionSet.version==2.0.0 +``` + +--- \ No newline at end of file diff --git a/docs/features.md b/docs/features.md deleted file mode 100644 index f1779211c..000000000 --- a/docs/features.md +++ /dev/null @@ -1,66 +0,0 @@ -# Features - ---- - -## Device and Software Repository - -- Repository that holds the provisioning targets and assignable software distributions. -- Targets can be logically grouped by **Target Types**. -- Includes a full software update history for every device. -- Supports pre-commission devices in the repository and plug and play (device is created when it authenticates for the first time). - ---- - -## Update Management - -- Directly deploy a defined software distribution to a device (via Management API). -- Update handling is independent of device type, integration approach, or connectivity. -- Optional user consent flow: download and install updates only after the respective end user has confirmed it. -- Mass cancel distribution of an update by invalidating the distribution set. -- Use action status codes for easier analysis. - ---- - -## Artifact Content Delivery - -- Partial downloads supported. -- Download resume supported (RFC7233). -- Content management by RESTful API and UI. -- Authorization based on software assignment (a device can only download what was assigned to it). -- Delta artifact hosting supported. -- Artifact signature hosting supported. -- Plug-point for artifact encryption (allows encryption of artifacts on upload). - ---- - -## Rollout [Campaign] Management - -- Secure handling of large volumes of devices at rollout creation time. -- Flexible deployment group definition as part of a rollout. -- Monitoring of rollout progress. -- Emergency rollout shutdown in case of update failures. -- Manually trigger the next rollout group. - ---- - -## Interfaces - -### Management API -- RESTful API. -- Create/Read/Update/Delete operations for provisioning targets (devices) and repository content (software). -- Manage and monitor software update operations. -- Online API documentation. -- JSON payload with Hypermedia support. -- Supports filtering, sorting, and paging. - -### Direct Device Integration API -- RESTful HTTP-based API for direct device integration. -- JSON payload. -- Traffic optimized (content-based ETag generation, not modified). -- Feedback channel from device. -- TLS encryption. - -### Device Management Federation API -- Indirect device integration through a device management service or application into hawkBit. -- Optimized for high service-to-service throughput with AMQP messaging interface. -- Separate AMQP vHost per tenant for maximum security. diff --git a/docs/graphics-source/rollout_groups.drawio b/docs/graphics-source/rollout_groups.drawio new file mode 100644 index 000000000..ecdb70032 --- /dev/null +++ b/docs/graphics-source/rollout_groups.drawio @@ -0,0 +1,156 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/graphics-source/rollouts_load.drawio b/docs/graphics-source/rollouts_load.drawio new file mode 100644 index 000000000..74ce09ae3 --- /dev/null +++ b/docs/graphics-source/rollouts_load.drawio @@ -0,0 +1,92 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/rollout.png b/docs/images/rollout.png deleted file mode 100644 index cf388cdfa..000000000 Binary files a/docs/images/rollout.png and /dev/null differ diff --git a/docs/images/rollout_groups.png b/docs/images/rollout_groups.png new file mode 100644 index 000000000..0a90bd1b7 Binary files /dev/null and b/docs/images/rollout_groups.png differ diff --git a/docs/images/rollout_load.png b/docs/images/rollout_load.png new file mode 100644 index 000000000..eb5dea8fa Binary files /dev/null and b/docs/images/rollout_load.png differ diff --git a/docs/management-api.md b/docs/management-api.md index b3eac7757..f29fb5f31 100644 --- a/docs/management-api.md +++ b/docs/management-api.md @@ -17,6 +17,9 @@ The current version of the Management API is `version 1 (v1)` with the URI `http - `PUT` - `DELETE` +### Query parameter +For filtering, sorting and paging as well as using the Feed Item Query Language (FIQL) see [Query parameters](query-parameters.md). + ### Headers For all requests an `Authorization` header has to be set. - Username: `username` @@ -32,21 +35,21 @@ Besides the relevant data (`name`, `description`, `createdBy` etc.) of a resourc A Distribution Set entity may have for example URIs to artifacts, Software Modules, Software Module Types and metadata. ```json "_links": { - "artifacts": { - "href": "http://localhost:8080/rest/v1/softwaremodules/83/artifacts" - }, - "self": { - "href": "http://localhost:8080/rest/v1/softwaremodules/83" - }, - "type": { - "href": "http://localhost:8080/rest/v1/softwaremoduletypes/43" - }, - "metadata": { - "href": "http://localhost:8080/rest/v1/softwaremodules/83/metadata?offset=0&limit=50" - } + "artifacts": { + "href": "http://localhost:8080/rest/v1/softwaremodules/83/artifacts" + }, + "self": { + "href": "http://localhost:8080/rest/v1/softwaremodules/83" + }, + "type": { + "href": "http://localhost:8080/rest/v1/softwaremoduletypes/43" + }, + "metadata": { + " href": "http://localhost:8080/rest/v1/softwaremodules/83/metadata?offset=0&limit=50" + } +} ``` - ## REST Doc