Skip to content

Commit 070fb38

Browse files
michaeltlombardimichaeltlombardi
authored
Merge pull request #929 from Gijsreyn/reference-doc-apt
Add reference documentation for DSC.PackageManagement/Apt
2 parents b54ed45 + e0b09a3 commit 070fb38

File tree

4 files changed

+363
-71
lines changed

4 files changed

+363
-71
lines changed

‎CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Please read the rest of this document to ensure a smooth contribution process.
2929
You can contribute to documentation either in the `docs` folder of this repository
3030
or in the [PowerShell-Docs-DSC](https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/) repository.
3131

32-
> [!INFO]
32+
> [!NOTE]
3333
> Documentation contributed to the `docs` folder in this repository is periodically synced to the [PowerShell-Docs-DSC](https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/) repository.
3434
3535
### Contributing to documentation related to maintaining or contributing to the DSC project

‎docs/reference/resources/DSC/PackageManagement/APT/examples/manage-packages-with-apt.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
description: >
3+
Demonstrates how to manage packages with the DSC.PackageManagement/Apt resource
4+
ms.date: 06/30/2025
5+
ms.topic: reference
6+
title: Manage packages with APT
7+
---
8+
9+
# Manage packages with APT
10+
11+
This example demonstrates how to use the `DSC.PackageManagement/Apt` resource to manage packages on Linux systems
12+
that use the APT package manager.
13+
14+
## Test if package is installed
15+
16+
The following snippet shows how you can use the resource with the [dsc resource test][00] command
17+
to check whether the `nginx` package exists.
18+
19+
```bash
20+
dsc resource test --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}'
21+
```
22+
23+
When the package is not installed, DSC returns the following result.
24+
25+
> [!NOTE]
26+
> Note that the version and source values can differ depending on your system's package repositories
27+
> and available package versions.
28+
29+
```yaml
30+
desiredState:
31+
packageName: nginx
32+
actualState:
33+
_exist: false
34+
packageName: nginx
35+
version: 1.24.0-2ubuntu7.3
36+
source: noble-updates,noble-security,now
37+
inDesiredState: false
38+
differingProperties:
39+
- _exist
40+
```
41+
42+
## Ensure a package is installed
43+
44+
To ensure the system is in the desired state, use the [dsc resource set][01]
45+
command.
46+
47+
```bash
48+
dsc resource set --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}'
49+
```
50+
51+
When the resource installs the package, DSC returns the following result:
52+
53+
```yaml
54+
beforeState:
55+
packageName: "nginx"
56+
_exist: false
57+
afterState:
58+
packageName: nginx
59+
version: "1.24.0-2ubuntu7.3"
60+
source: noble-updates,noble-security,now
61+
changedProperties:
62+
- _exist
63+
```
64+
65+
You can test the instance again to confirm that the package exists:
66+
67+
```bash
68+
dsc resource test --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}'
69+
```
70+
71+
```yaml
72+
desiredState:
73+
packageName: nginx
74+
actualState:
75+
_exist: true
76+
packageName: nginx
77+
version: 1.24.0-2ubuntu7.3
78+
source: noble-updates,noble-security,now
79+
inDesiredState: true
80+
differingProperties: []
81+
```
82+
83+
## Uninstall a package
84+
85+
To uninstall a package, set the `_exist` property to `false`:
86+
87+
```bash
88+
dsc resource set --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx", "_exist": false}'
89+
```
90+
91+
To verify the package no longer exists, use the `dsc resource get` command
92+
93+
```powershell
94+
dsc resource get --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}'
95+
```
96+
97+
```yaml
98+
actualState:
99+
packageName: nginx
100+
_exist: false
101+
```
102+
103+
<!-- Link reference definitions -->
104+
[00]: ../../../../../cli/resource/test.md
105+
[01]: ../../../../../cli/resource/set.md

‎docs/reference/resources/DSC/PackageManagement/APT/index.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
description: DSC.PackageManagement/Apt resource reference documentation
3+
ms.date: 06/30/2025
4+
ms.topic: reference
5+
title: DSC.PackageManagement/Apt
6+
---
7+
8+
# DSC.PackageManagement/Apt
9+
10+
## Synopsis
11+
12+
Manage packages with the advanced package tool (APT) on Linux systems.
13+
14+
> [!IMPORTANT]
15+
> The `DSC.PackageManagement/Apt` resource is a proof-of-concept example
16+
> for use with DSC. Don't use it in production.
17+
18+
## Metadata
19+
20+
```yaml
21+
Version : 0.1.0
22+
Kind : resource
23+
Tags : [Linux, apt, PackageManagement]
24+
Author : Microsoft
25+
```
26+
27+
## Instance definition syntax
28+
29+
```yaml
30+
resources:
31+
- name: <instance name>
32+
type: DSC.PackageManagement/Apt
33+
properties:
34+
# Required properties
35+
packageName: string
36+
# Instance properties
37+
_exist: boolean
38+
version: string
39+
```
40+
41+
## Description
42+
43+
The `DSC.PackageManagement/Apt` resource enables you to idempotently manage packages with the Advanced Package Tool (APT) on
44+
Linux systems. The resource can:
45+
46+
- Install packages
47+
- Uninstall packages
48+
- Check if a package is installed
49+
- Verify the version of an installed package
50+
51+
> [!NOTE]
52+
> This resource only works on Linux systems that use the APT package manager, such as Ubuntu and Debian.
53+
54+
## Requirements
55+
56+
- A Linux system with APT installed
57+
- Administrative privileges (root or sudo access) to install and remove packages
58+
59+
## Capabilities
60+
61+
The resource has the following capabilities:
62+
63+
- `get` - You can use the resource to retrieve the actual state of an instance.
64+
- `set` - You can use the resource to enforce the desired state for an instance.
65+
- `export` - You can use the resource to export the current state of the system.
66+
67+
This resource uses the synthetic test functionality of DSC to determine whether an instance is in
68+
the desired state. For more information about resource capabilities, see
69+
[DSC resource capabilities][00].
70+
71+
## Examples
72+
73+
1. [Manage packages with APT](./examples/manage-packages-with-apt.md) - Shows how to install, uninstall,
74+
and check packages with the `DSC.PackageManagement/Apt` resource.
75+
76+
## Properties
77+
78+
The following list describes the properties for the resource.
79+
80+
- **Required properties:** <a id="required-properties"></a> The following properties are always
81+
required when defining an instance of the resource. An instance that doesn't define each of these
82+
properties is invalid. For more information, see the "Required resource properties" section in
83+
[DSC resource properties][01]
84+
85+
- [packageName](#packagename) - The name of the package to query or install.
86+
87+
- **Key properties:** <a id="key-properties"></a> The following properties uniquely identify an
88+
instance. If two instances of a resource have the same values for their key properties, the
89+
instances are conflicting. For more information about key properties, see the "Key resource
90+
properties" section in [DSC resource properties][02].
91+
92+
- [packageName](#packagename) (required) - The name of the package to query or install.
93+
94+
- **Instance properties:** <a id="instance-properties"></a> The following properties are optional.
95+
They define the desired state for an instance of the resource.
96+
97+
- [_exist](#_exist) - Defines whether the package should exist.
98+
- [version](#version) - The version of the package to install.
99+
100+
- **Read-only properties:** <a id="read-only-properties"></a> The resource returns the following
101+
properties, but they aren't configurable. For more information about read-only properties, see
102+
the "Read-only resource properties" section in [DSC resource properties][03].
103+
104+
- [source](#source) - Indicates the source of the package.
105+
106+
### packageName
107+
108+
<details><summary>Expand for <code>packageName</code> property metadata</summary>
109+
110+
```yaml
111+
Type : string
112+
IsRequired : true
113+
IsKey : true
114+
IsReadOnly : false
115+
IsWriteOnly : false
116+
```
117+
118+
</details>
119+
120+
Defines the name of the package to query or install. This property is required and serves as the key for uniquely
121+
identifying the package.
122+
123+
### _exist
124+
125+
<details><summary>Expand for <code>_exist</code> property metadata</summary>
126+
127+
```yaml
128+
Type : boolean
129+
IsRequired : false
130+
IsKey : false
131+
IsReadOnly : false
132+
IsWriteOnly : false
133+
DefaultValue : true
134+
```
135+
136+
</details>
137+
138+
The `_exist` canonical resource property determines whether a package should exist. When the
139+
value for `_exist` is `true`, the resource installs the package if it doesn't exist. When
140+
the value for `_exist` is `false`, the resource removes or uninstalls the package if it does exist.
141+
The default value for this property when not specified for an instance is `true`.
142+
143+
### version
144+
145+
<details><summary>Expand for <code>version</code> property metadata</summary>
146+
147+
```yaml
148+
Type : string
149+
IsRequired : false
150+
IsKey : false
151+
IsReadOnly : false
152+
IsWriteOnly : false
153+
```
154+
155+
</details>
156+
157+
Defines the version of the package to install. If not specified, the latest available version will be installed.
158+
159+
### source
160+
161+
<details><summary>Expand for <code>source</code> property metadata</summary>
162+
163+
```yaml
164+
Type : string
165+
IsRequired : false
166+
IsKey : false
167+
IsReadOnly : true
168+
IsWriteOnly : false
169+
```
170+
171+
</details>
172+
173+
Indicates the source of the package. This is a read-only property returned by the resource after a `get` operation.
174+
175+
## Exit codes
176+
177+
The resource returns the following exit codes from operations:
178+
179+
- [0](#exit-code-0) - Success
180+
- [1](#exit-code-1) - Invalid parameter
181+
182+
### Exit code 0
183+
184+
Indicates the resource operation completed without errors.
185+
186+
### Exit code 1
187+
188+
Indicates the resource operation failed due to an invalid parameter. When the resource returns this
189+
exit code, it also emits an error message with details about the invalid parameter.
190+
191+
## See also
192+
193+
- [For more information about APT](https://wiki.debian.org/Apt)
194+
195+
<!-- Link definitions -->
196+
[00]: ../../../../../concepts/resources/capabilities.md
197+
[01]: ../../../../../concepts/resources/properties.md#required-resource-properties
198+
[02]: ../../../../../concepts/resources/properties.md#key-resource-properties
199+
[03]: ../../../../../concepts/resources/properties.md#read-only-resource-properties

0 commit comments

Comments
 (0)