diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 634f9cfce..107965376 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ Please read the rest of this document to ensure a smooth contribution process. You can contribute to documentation either in the `docs` folder of this repository or in the [PowerShell-Docs-DSC](https://github.com/MicrosoftDocs/PowerShell-Docs-DSC/) repository. -> [!INFO] +> [!NOTE] > 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. ### Contributing to documentation related to maintaining or contributing to the DSC project diff --git a/docs/reference/resources/DSC/PackageManagement/APT/examples/manage-packages-with-apt.md b/docs/reference/resources/DSC/PackageManagement/APT/examples/manage-packages-with-apt.md new file mode 100644 index 000000000..ed18727c8 --- /dev/null +++ b/docs/reference/resources/DSC/PackageManagement/APT/examples/manage-packages-with-apt.md @@ -0,0 +1,105 @@ +--- +description: > + Demonstrates how to manage packages with the DSC.PackageManagement/Apt resource +ms.date: 06/30/2025 +ms.topic: reference +title: Manage packages with APT +--- + +# Manage packages with APT + +This example demonstrates how to use the `DSC.PackageManagement/Apt` resource to manage packages on Linux systems +that use the APT package manager. + +## Test if package is installed + +The following snippet shows how you can use the resource with the [dsc resource test][00] command +to check whether the `nginx` package exists. + +```bash +dsc resource test --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}' +``` + +When the package is not installed, DSC returns the following result. + +> [!NOTE] +> Note that the version and source values can differ depending on your system's package repositories +> and available package versions. + +```yaml +desiredState: + packageName: nginx +actualState: + _exist: false + packageName: nginx + version: 1.24.0-2ubuntu7.3 + source: noble-updates,noble-security,now +inDesiredState: false +differingProperties: + - _exist +``` + +## Ensure a package is installed + +To ensure the system is in the desired state, use the [dsc resource set][01] +command. + +```bash +dsc resource set --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}' +``` + +When the resource installs the package, DSC returns the following result: + +```yaml +beforeState: + packageName: "nginx" + _exist: false +afterState: + packageName: nginx + version: "1.24.0-2ubuntu7.3" + source: noble-updates,noble-security,now +changedProperties: +- _exist +``` + +You can test the instance again to confirm that the package exists: + +```bash +dsc resource test --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}' +``` + +```yaml +desiredState: + packageName: nginx +actualState: + _exist: true + packageName: nginx + version: 1.24.0-2ubuntu7.3 + source: noble-updates,noble-security,now +inDesiredState: true +differingProperties: [] +``` + +## Uninstall a package + +To uninstall a package, set the `_exist` property to `false`: + +```bash +dsc resource set --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx", "_exist": false}' +``` + +To verify the package no longer exists, use the `dsc resource get` command + +```powershell +dsc resource get --resource DSC.PackageManagement/Apt --input '{"packageName":"nginx"}' +``` + +```yaml +actualState: + packageName: nginx + _exist: false +``` + + +[00]: ../../../../../cli/resource/test.md +[01]: ../../../../../cli/resource/set.md diff --git a/docs/reference/resources/DSC/PackageManagement/APT/index.md b/docs/reference/resources/DSC/PackageManagement/APT/index.md new file mode 100644 index 000000000..ab5ad2dec --- /dev/null +++ b/docs/reference/resources/DSC/PackageManagement/APT/index.md @@ -0,0 +1,199 @@ +--- +description: DSC.PackageManagement/Apt resource reference documentation +ms.date: 06/30/2025 +ms.topic: reference +title: DSC.PackageManagement/Apt +--- + +# DSC.PackageManagement/Apt + +## Synopsis + +Manage packages with the advanced package tool (APT) on Linux systems. + +> [!IMPORTANT] +> The `DSC.PackageManagement/Apt` resource is a proof-of-concept example +> for use with DSC. Don't use it in production. + +## Metadata + +```yaml +Version : 0.1.0 +Kind : resource +Tags : [Linux, apt, PackageManagement] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: DSC.PackageManagement/Apt + properties: + # Required properties + packageName: string + # Instance properties + _exist: boolean + version: string +``` + +## Description + +The `DSC.PackageManagement/Apt` resource enables you to idempotently manage packages with the Advanced Package Tool (APT) on +Linux systems. The resource can: + +- Install packages +- Uninstall packages +- Check if a package is installed +- Verify the version of an installed package + +> [!NOTE] +> This resource only works on Linux systems that use the APT package manager, such as Ubuntu and Debian. + +## Requirements + +- A Linux system with APT installed +- Administrative privileges (root or sudo access) to install and remove packages + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of an instance. +- `set` - You can use the resource to enforce the desired state for an instance. +- `export` - You can use the resource to export the current state of the system. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. For more information about resource capabilities, see +[DSC resource capabilities][00]. + +## Examples + +1. [Manage packages with APT](./examples/manage-packages-with-apt.md) - Shows how to install, uninstall, + and check packages with the `DSC.PackageManagement/Apt` resource. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. An instance that doesn't define each of these + properties is invalid. For more information, see the "Required resource properties" section in + [DSC resource properties][01] + + - [packageName](#packagename) - The name of the package to query or install. + +- **Key properties:** The following properties uniquely identify an + instance. If two instances of a resource have the same values for their key properties, the + instances are conflicting. For more information about key properties, see the "Key resource + properties" section in [DSC resource properties][02]. + + - [packageName](#packagename) (required) - The name of the package to query or install. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [_exist](#_exist) - Defines whether the package should exist. + - [version](#version) - The version of the package to install. + +- **Read-only properties:** The resource returns the following + properties, but they aren't configurable. For more information about read-only properties, see + the "Read-only resource properties" section in [DSC resource properties][03]. + + - [source](#source) - Indicates the source of the package. + +### packageName + +
Expand for packageName property metadata + +```yaml +Type : string +IsRequired : true +IsKey : true +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the name of the package to query or install. This property is required and serves as the key for uniquely +identifying the package. + +### _exist + +
Expand for _exist property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +DefaultValue : true +``` + +
+ +The `_exist` canonical resource property determines whether a package should exist. When the +value for `_exist` is `true`, the resource installs the package if it doesn't exist. When +the value for `_exist` is `false`, the resource removes or uninstalls the package if it does exist. +The default value for this property when not specified for an instance is `true`. + +### version + +
Expand for version property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Defines the version of the package to install. If not specified, the latest available version will be installed. + +### source + +
Expand for source property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : true +IsWriteOnly : false +``` + +
+ +Indicates the source of the package. This is a read-only property returned by the resource after a `get` operation. + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Invalid parameter + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed due to an invalid parameter. When the resource returns this +exit code, it also emits an error message with details about the invalid parameter. + +## See also + +- [For more information about APT](https://wiki.debian.org/Apt) + + +[00]: ../../../../../concepts/resources/capabilities.md +[01]: ../../../../../concepts/resources/properties.md#required-resource-properties +[02]: ../../../../../concepts/resources/properties.md#key-resource-properties +[03]: ../../../../../concepts/resources/properties.md#read-only-resource-properties diff --git a/resources/apt/apt.dsc.resource.json b/resources/apt/apt.dsc.resource.json index a03c067f2..4e8e214a2 100644 --- a/resources/apt/apt.dsc.resource.json +++ b/resources/apt/apt.dsc.resource.json @@ -1,74 +1,62 @@ { - "$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json", - "type": "DSC.PackageManagement/Apt", - "description": "Manage packages with the advanced package tool (APT)", - "tags": [ - "Linux", - "apt", - "PackageManagement" - ], - "version": "0.1.0", - "get": { - "executable": "apt.dsc.resource.sh", - "args": [ - "get" - ], - "input": "env" - }, - "set": { - "executable": "apt.dsc.resource.sh", - "args": [ - "set" - ], - "input": "env", - "implementsPretest": true, - "handlesExist": true - }, - "export": { - "executable": "apt.dsc.resource.sh", - "args": [ - "export" - ], - "input": "env" - }, - "exitCodes": { - "0": "Success", - "1": "Invalid parameter" - }, - "schema": { - "embedded": { - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/resources/DSC/PackageManagement/apt/v0.1.0/schema.json", - "title": "Apt", - "description": "Managed packages using apt", - "type": "object", - "required": [ - "packageName" - ], - "additionalProperties": false, - "properties": { - "packageName": { - "type": "string", - "title": "Package Name", - "description": "Defines the name of the package to query or install" - }, - "version": { - "type": "string", - "title": "Version", - "description": "Defines the version of the package to install" - }, - "source": { - "type": "string", - "title": "Source", - "description": "Indicates the source of the package", - "readOnly": true - }, - "_exist": { - "type": "boolean", - "title": "Exist", - "description": "Defines if the package should exist or not" - } - } + "$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json", + "type": "DSC.PackageManagement/Apt", + "description": "Manage packages with the advanced package tool (APT)", + "tags": ["Linux", "apt", "PackageManagement"], + "version": "0.1.0", + "get": { + "executable": "apt.dsc.resource.sh", + "args": ["get"], + "input": "env" + }, + "set": { + "executable": "apt.dsc.resource.sh", + "args": ["set"], + "input": "env", + "implementsPretest": true, + "handlesExist": true + }, + "export": { + "executable": "apt.dsc.resource.sh", + "args": ["export"], + "input": "env" + }, + "exitCodes": { + "0": "Success", + "1": "Invalid parameter" + }, + "schema": { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/resources/DSC/PackageManagement/apt/v0.1.0/schema.json", + "title": "Apt", + "description": "Managed packages using apt", + "type": "object", + "required": ["packageName"], + "additionalProperties": false, + "properties": { + "packageName": { + "type": "string", + "title": "Package Name", + "description": "Defines the name of the package to query or install" + }, + "version": { + "type": "string", + "title": "Version", + "description": "Defines the version of the package to install" + }, + "source": { + "type": "string", + "title": "Source", + "description": "Indicates the source of the package", + "readOnly": true + }, + "_exist": { + "type": "boolean", + "title": "Exist", + "description": "Defines if the package should exist or not" } + } } + } }