Extend hawkBit Documentation (#2920)
This commit is contained in:
Desislava Marinova
committed by
GitHub
GitHub
parent
30fd475b57
commit
a82f4cc9f6
260
docs/entity-definitions.md
Normal file
260
docs/entity-definitions.md
Normal file
@@ -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.<key>` | Metadata value by key | String |
|
||||
| `controllerAttributes.<key>` | 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.<key>` | 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.<key>` | 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
|
||||
```
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user