Skip to content

Commit 7f5e1de

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #292966 from v-thepet/iot8
Freshness Edit: IoT-hub-device 8
2 parents 9051584 + 5561815 commit 7f5e1de

File tree

5 files changed

+262
-272
lines changed

5 files changed

+262
-272
lines changed

‎articles/iot-hub-device-update/device-update-apt-manifest.md

Lines changed: 95 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,24 @@
11
---
2-
title: Understand Device Update for Azure IoT Hub apt manifest
3-
description: Understand how Device Update for IoT Hub uses apt manifest for a package-based update.
2+
title: Azure Device Update for IoT Hub apt manifest
3+
description: Understand how Azure Device Update for IoT Hub uses the apt manifest for a package-based update.
44
author: vimeht
55
ms.author: vimeht
6-
ms.date: 2/17/2021
6+
ms.date: 01/21/2025
77
ms.topic: concept-article
88
ms.service: azure-iot-hub
99
ms.subservice: device-update
1010
---
1111

1212

13-
# Device Update apt manifest
13+
# Azure Device Update for IoT Hub apt manifest
1414

15-
The apt manifest is a JSON file that describes an update details required by apt update handler. This file can be imported into Device Update for IoT Hub just like any other update.
15+
This article describes the apt manifest, a JSON file that describes update details required by the apt update handler. You can import this file into Device Update just like any other update. For more information, see [Import an update to Device Update](import-update.md).
1616

17-
For more information, see [Import an update to Device Update for IoT Hub](import-update.md).
17+
When you deliver an apt manifest to a Device Update agent as an update, the agent processes the manifest and carries out the necessary operations. These operations include downloading and installing the packages specified in the apt manifest file and their dependencies from a designated repository.
1818

19-
## Overview
19+
Device Update supports the apt update type and [update handler](device-update-agent-overview.md#update-handlers). This support allows the Device Update agent to evaluate the installed Debian packages and update the necessary packages.
2020

21-
When an apt manifest is delivered to a Device Update agent as an update, the agent processes the manifest and carries out the necessary operations. These operations include downloading and installing the packages specified in the apt manifest file and their dependencies from a designated repository.
22-
23-
Device Update supports apt updateType and apt [update handler](device-update-agent-overview.md#update-handlers). This support allows the Device Update agent to evaluate the installed Debian packages and update the necessary packages.
21+
You can use an apt manifest to update the Device Update agent itself and its dependencies. List the device update agent name and desired version in the apt manifest as you would any other package. You can then import this apt manifest and deploy it through the Device Update pipeline.
2422

2523
## Schema
2624

@@ -60,122 +58,115 @@ For example:
6058

6159
Each apt manifest includes the following properties:
6260

63-
* **Name**: The name for this apt manifest. This can be whatever name or ID is meaningful for your scenarios. For example, `contoso-iot-edge`.
64-
* **Version**: A version number for this apt Manifest. For example, `1.0.0.0`.
65-
* **Packages**: A list of objects containing package-specific properties.
66-
* **Name**: The name or ID of the package. For example, `iotedge`.
67-
* **Version**: The desired version criteria for the package. For example, `1.0.8-2`. The version value shouldn't contain an equal sign. If version is omitted, the latest available version of specified package will be installed.
61+
- **Name**: A name for this apt manifest, which can be any meaningful name or ID that fits your scenario. For example, `contoso-iot-edge`.
62+
- **Version**: A version number for this apt manifest, for example `1.0.0.0`.
63+
- **Packages**: A list of objects containing package-specific properties.
64+
- **Name**: The package name or ID, for example `iotedge`.
65+
- **Version**: The desired package version criteria, for example, `1.0.8-2`.
6866

69-
Currently only exact version number is supported. The version number is the desired Debian package version in format **[epoch:]upstream_version[-debian_revision]**, where **epoch** is an unsigned int and **upstream_version** can include alphanumerics and characters such as ".","+","-" and "~". It should start with a digit.
67+
### Versioning
7068

71-
> [!NOTE]
72-
> '1.0.8' is equal to '1.0.8-0'
69+
The apt manifest supports only exact version numbers. The version number is the desired Debian package version in format `<epoch>:<upstream_version>-<debian_revision>`, where `epoch` is an unsigned int and `upstream_version` starts with a digit and can include alphanumerics and characters such as `.`, `,`, `+`, `-`, and `~`. The version value shouldn't contain an equal sign.
7370

74-
For example, `"name":"iotedge"` and `"version":"1.0.8-2"` is equivalent to installing a package using command `apt-get install iotedge=1.0.8-2`
71+
For example, `"name":"iotedge"` and `"version":"1.0.8-2"` is equivalent to installing a package using command `apt-get install iotedge=1.0.8-2`. Version `1.0.8` is equal to `1.0.8-0`.
7572

76-
For more information about how Debian packages are versioned, see [the Debian policy manual](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-version)
73+
If version is omitted, Device Update installs the latest available version of the specified package. For more information about how Debian packages are versioned, see the [Debian policy manual](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-version).
7774

7875
> [!NOTE]
79-
> The apt package manager ignores versioning requirements given by a package when the dependent packages to install are being automatically resolved. Unless explicit versions of dependent packages are given they will use the latest, even though the package itself may specify a strict requirement (=) on a given version. This automatic resolution can lead to errors regarding an unmet dependency. [Learn More](https://unix.stackexchange.com/questions/350192/apt-get-not-properly-resolving-a-dependency-on-a-fixed-version-in-a-debian-ubunt)
76+
> The apt package manager ignores versioning requirements given by a package when the dependent packages to install are being automatically resolved. Unless explicit versions of dependent packages are given they use the latest, even though the package itself may specify a strict requirement (=) on a given version. This automatic resolution can lead to errors regarding an unmet dependency.
77+
>
78+
> Therefore, when you install a specific version of a package, it's best to also include the explicit versions of the dependent packages to install. For more information, see [apt-get not properly resolving a dependency on a fixed version in a Debian/Ubuntu package](https://unix.stackexchange.com/questions/350192/apt-get-not-properly-resolving-a-dependency-on-a-fixed-version-in-a-debian-ubunt).
8079
81-
If you're updating a specific version of the Azure IoT Edge security daemon, then you should include the desired version of the `aziot-edge` package and its dependent `aziot-identity-service` package in your apt manifest.
82-
For more information, see [How to update IoT Edge](../iot-edge/how-to-update-iot-edge.md#update-the-security-subsystem).
80+
If you update a specific version of the Azure IoT Edge security daemon, you should include the desired version of the `aziot-edge` package and its dependent `aziot-identity-service` package in your apt manifest. For more information, see [How to update IoT Edge](../iot-edge/how-to-update-iot-edge.md#update-the-security-subsystem).
8381

84-
An apt manifest can be used to update Device Update agent and its dependencies. List the device update agent name and desired version in the apt manifest, like you would for any other package. This apt manifest can then be imported and deployed through the Device Update for IoT Hub pipeline.
82+
## Installed criteria
8583

86-
## Removing packages
84+
The recommended installed criteria value for an apt manifest is `<name>-<version>`, where `<name>` is the name of the apt manifest and `<version>` is its version. For example, `contoso-iot-edge-1.0.0.0`.
8785

88-
You can also use an apt manifest to remove installed packages from your device. A single apt manifest can be used to remove, add, and update multiple packages.
86+
## Package removal
8987

90-
To remove a package, add a minus sign "-" after the package name. You shouldn't include a version number for the packages you're removing. Removing a package through an apt manifest doesn't remove its dependencies and configurations.
88+
You can also use an apt manifest to remove installed packages from devices. You can use a single apt manifest to remove, add, and update multiple packages.
89+
90+
To remove a package, add a minus sign `-` after the package name. Don't include a version number for the packages you're removing. Removing a package through an apt manifest doesn't remove its dependencies and configurations.
91+
92+
For example, the following apt manifest removes the package `contoso1` from any devices it's deployed to.
9193

92-
For example:
9394

9495
```json
9596
{
9697
"name": "contoso-video",
9798
"version": "2.0.0.1",
9899
"packages": [
99100
{
100-
"name" : "foo-"
101-
}
102-
]
103-
}
104-
```
105-
106-
This apt manifest will remove the package "foo" from the device(s) it's deployed to.
107-
108-
## Recommended value for installed criteria
109-
110-
The installed criteria for an apt manifest is `<name>-<version>` where `<name>` is the name of the apt Manifest and `<version>` is the version of the apt manifest. For example, `contoso-iot-edge-1.0.0.0`.
111-
112-
## Guidelines on creating an apt manifest
113-
114-
While creating the apt manifest, there are some guidelines to keep in mind:
115-
116-
* Always ensure that the apt manifest is a well-formed json file.
117-
* Each apt manifest should have a unique version. Try to come up with a standardized methodology to increment the version of the apt manifest, so that it makes sense for your scenarios and can be easily followed.
118-
* When it comes to the desired state of each individual package, specify the exact name and version of the package that you would like to install on your device. Always validate the values against the package repository that you intend to use as the source for the package.
119-
* Ensure that the packages in the apt manifest are listed in the order they should be installed/removed.
120-
* Always validate the installation of packages on a test device to ensure the outcome is desired.
121-
* When installing a specific version of a package (For example, `iotedge 1.0.9-1`), it's best practice to also have in the apt manifest the explicit versions of the dependent packages to be installed (For example, `libiothsm 1.0.9-1`)
122-
* While it's not mandated, always ensure your apt manifest is cumulative to avoid getting your device into an unknown state. A cumulative update will ensure that your devices have the desired version of every package you care about even if the device has skipped an apt update deployment because of failure in installation, or being taken offline
123-
124-
For example:
125-
126-
**Base apt manifest**
127-
128-
```JSON
129-
{
130-
"name": "contoso-iot-edge",
131-
"version": "1.0",
132-
"packages": [
133-
{
134-
"name": "foo",
135-
"version": "1.0.1"
136-
}
137-
]
138-
}
139-
```
140-
141-
**Bad update**
142-
143-
This update includes the bar package, but not the foo package.
144-
145-
```JSON
146-
{
147-
"name": "contoso-iot-edge",
148-
"version": "2.0",
149-
"packages": [
150-
{
151-
"name": "bar",
152-
"version": "3.0.2"
153-
}
154-
]
155-
}
156-
```
157-
158-
**Good update**
159-
160-
This update includes foo package, and also includes bar package.
161-
162-
```JSON
163-
{
164-
"name": "contoso-iot-edge",
165-
"version": "2.0",
166-
"packages": [
167-
{
168-
"name": "foo",
169-
"version": "1.0.1"
170-
},
171-
{
172-
"name": "bar",
173-
"version": "3.0.2"
101+
"name" : "contoso1-"
174102
}
175103
]
176104
}
177105
```
178106

179-
## Next steps
107+
## Apt manifest creation guidelines
108+
109+
Keep the following guidelines in mind when you create an apt manifest:
110+
111+
- Ensure that the apt manifest is a well-formed JSON file.
112+
- Give each apt manifest a unique version. Try to come up with a standardized methodology to increment the version of the apt manifest, so it makes sense for your scenarios and is easy to follow.
113+
- For the desired state of each individual package, specify the exact name and version of the package you want to install on your device. Always validate the values against the contents of the source package repository.
114+
- List the packages in the apt manifest in the order they should be installed or removed.
115+
- Always validate the installation of packages on a test device to ensure the desired outcome.
116+
- When you install a specific version of a package, for example `iotedge 1.0.9-1`, also include the explicit versions of the dependent packages to install, for example `libiothsm 1.0.9-1`.
117+
- While not required, always making your apt manifest cumulative avoids getting devices into an unknown state. A cumulative update ensures that your devices have the desired version of every relevant package, even if the device skipped an update because of installation failure or being offline.
118+
119+
For example, consider the following base apt manifest:
120+
121+
```JSON
122+
{
123+
"name": "contoso-iot-edge",
124+
"version": "1.0",
125+
"packages": [
126+
{
127+
"name": "contoso1",
128+
"version": "1.0.1"
129+
}
130+
]
131+
}
132+
```
133+
134+
The following version 2.0 update includes the `contoso2` package, but not the `contoso1` package. All devices that receive the 2.0 update might not have the `contoso1` package.
135+
136+
```JSON
137+
{
138+
"name": "contoso-iot-edge",
139+
"version": "2.0",
140+
"packages": [
141+
{
142+
"name": "contoso2",
143+
"version": "3.0.2"
144+
}
145+
]
146+
}
147+
```
148+
149+
The following version 2.0 cumulative update includes both the `contoso1` and `contoso2` packages:
150+
151+
```JSON
152+
{
153+
"name": "contoso-iot-edge",
154+
"version": "2.0",
155+
"packages": [
156+
{
157+
"name": "contoso1",
158+
"version": "1.0.1"
159+
},
160+
{
161+
"name": "contoso2",
162+
"version": "3.0.2"
163+
}
164+
]
165+
}
166+
```
167+
168+
## Related content
169+
170+
- [Import an update to Device Update](import-update.md)
171+
- [Device Update import manifest concepts](import-concepts.md)
180172

181-
[Import an update to Device Update](import-update.md)

0 commit comments

Comments
 (0)