Config Tasks¶

Config tasks are post-provisioning configuration steps that run on compute nodes or after resource group/deployment staging. They automate software installation, security configuration, and custom scripting via Ansible.

Config tasks appear in three places:

Compute node config block — runs on the specific VM after it's provisioned
ResourceGroup Template postConfig block — runs after all resources in the RG are deployed
Deployment Template postConfig block — runs after all resource groups are deployed

When used in postConfig, you typically need the limit key to specify which host to target:

postConfig:
  - name: invoke-psscript
    limit: "{{computenode.vmdb.fqdn}}"
    variables:
      script: |
        Write-Host "Post-config task"

Built-in Tasks¶

Name	Supports States	Description
firewall-rule	Yes	Add/Remove Windows Firewall rules
install-rds	No	Install Remote Desktop Services
install-sql	No	Install Microsoft SQL Server
invoke-psscript	No	Execute custom PowerShell scripts
local-group-member	Yes	Add/Remove local group members
package	Yes	Install/Uninstall software packages
registry-keys	Yes	Add/Remove Windows registry keys
request-certificate-acme	No	Request ACME (Let's Encrypt) certificates
user-rights-assignment	Yes	Add/Remove Windows user rights
win-feature	Yes	Install/Uninstall Windows features

Tasks that "Support States" can be used to both add (present) and remove (absent) configuration.

Custom config tasks can also be added using customer-owned Git repositories.

firewall-rule¶

Create or modify Windows Firewall rules. At least one of name or group must be defined.

Variable	Required	Type	Description
`name`	Yes (if no `group`)	String	Name of the firewall rule
`group`	Yes (if no `name`)	String	Name of the firewall group
`localport`	No	String	Port(s) for the rule (e.g., `"80"`, `"80,443"`)
`action`	No	String	`allow` or `block`
`direction`	No	String	`in` or `out`
`protocol`	No	String	`TCP`, `UDP`, etc.
`state`	No	String	`present` (default) or `absent`
`enabled`	No	Bool	Whether the rule is enabled (default: `true`)

- name: firewall-rule
  variables:
    name: allow-https
    action: allow
    localport: 443
    protocol: tcp
    direction: in

install-rds¶

Install and configure Remote Desktop Services. Both variables are mandatory.

Variable	Required	Type	Description
`rd_license_server`	Yes	String	FQDN of the RDS license server
`rd_users`	Yes	String	User group(s) allowed to access RDS (comma-separated)

- name: install-rds
  variables:
    rd_license_server: rdslicense.yourdomain.local
    rd_users: '"yourdomain\group1","yourdomain\group2"'

install-sql¶

Install Microsoft SQL Server.

Core settings¶

Variable	Required	Type	Description
`mssql_version`	Yes	String	SQL Server version (e.g., `sql17dev`, `sql19dev`, `sql22dev`)
`mssql_features`	Yes	String	Comma-separated features to install (e.g., `SQLENGINE,FULLTEXT,IS`)
`mssql_instance_name`	No	String	SQL instance name (default: `MSSQLSERVER`)
`mssql_collation`	No	String	SQL collation (default: `Latin1_General_CI_AS`)
`mssql_port`	No	Number	TCP port for the SQL instance (default: `1433`)
`mssql_tempdrive`	No	String	Drive letter to host the tempdb files (e.g., `Z`). Falls back to the user data drive when unset.
`mssql_updateversion`	No	String	Cumulative update to apply (default: `latest`)
`mssql_environment`	No	String	Environment tag used to pick the backup share (`Prod` or `NonProd`, default: `NonProd`)
`mssql_location`	No	String	Azure region used to pick the backup share (default: `westeurope`)
`mssql_base_ldap_path`	No	String	LDAP base path used when resolving AD objects

Service accounts¶

Variable	Required	Type	Description
`mssql_sqlsvc_account`	No	String	SQL Server service account (`DOMAIN\user` format)
`mssql_sqlsvc_account_pass`	No	String	SQL Server service account password
`mssql_agentsvc_account`	No	String	SQL Agent service account
`mssql_agentsvc_account_pass`	No	String	SQL Agent service account password

Permissions¶

Variable	Required	Type	Description
`mssql_sysadmin_accounts`	No	List	Accounts/groups granted the `sysadmin` server role
`mssql_dbops_login`	No	String	Account/group granted the database operator login

TempDB¶

Variable	Required	Type	Description
`mssql_sqltempDB_filecount`	No	Number	Number of tempdb data files (default: `8`)
`mssql_sqltempDB_filesize`	No	Number	Initial size in MB of each tempdb data file (default: `1024`)

SQL configuration options¶

These map to sp_configure settings applied after install.

Variable	Required	Type	Description
`mssql_configuration_option_fillfactor`	No	Number	`fill factor (%)` (default: `0`)
`mssql_configuration_option_costthresholdforparallelism`	No	Number	`cost threshold for parallelism` (default: `50`)
`mssql_configuration_option_maxdegreeofparallelism`	No	Number	`max degree of parallelism` (default: `4`)
`mssql_configuration_option_scanforstartupprocs`	No	Number	`scan for startup procs` (default: `0`)
`mssql_configuration_option_clrenabled`	No	Number	`clr enabled` (default: `0`)
`mssql_configuration_option_remoteadminconnections`	No	Number	`remote admin connections` (default: `1`)
`mssql_configuration_option_backupcompressiondefault`	No	Number	`backup compression default` (default: `1`)
`mssql_configuration_option_filestreamaccesslevel`	No	Number	`filestream access level` (default: `0`)
`mssql_configuration_option_optimizeforadhocworkloads`	No	Number	`optimize for ad hoc workloads` (default: `1`)
`mssql_configuration_option_clrstrictsecurity`	No	Number	`clr strict security` (default: `1`)
`mssql_configuration_option_databasemailxps`	No	Number	`Database Mail XPs` (default: `1`)
`mssql_configuration_option_oleautomationprocedures`	No	Number	`Ole Automation Procedures` (default: `0`)
`mssql_configuration_option_xpcmdshell`	No	Number	`xp_cmdshell` (default: `0`)
`mssql_configuration_option_adhocdistributedqueries`	No	Number	`Ad Hoc Distributed Queries` (default: `0`)
`mssql_configuration_options_json`	No	String	JSON array of additional `sp_configure` options. Format: `[{"name":"<option>","value":<int>,"RestartService":<bool>}]`

- name: install-sql
  variables:
    mssql_version: sql22dev
    mssql_features: SQLENGINE,FULLTEXT,IS
    mssql_instance_name: MSSQLSERVER
    mssql_collation: Latin1_General_CI_AS
    mssql_port: 1433
    mssql_tempdrive: Z
    mssql_updateversion: latest
    mssql_base_ldap_path: "{{adresourceprovider.AD_USER_RESOURCE_OU}}"
    mssql_sysadmin_accounts: ["yourdomain\\{{rbacresourcegroup.rbacsysadmin.groupname}}"]
    mssql_dbops_login: "yourdomain\\{{rbacresourcegroup.rbacdbops.groupname}}"
    mssql_sqlsvc_account: "yourdomain\\{{serviceaccount.svcdb.svcname}}"
    mssql_sqlsvc_account_pass: "{{serviceaccount.svcdb.svcpassword}}"
    mssql_agentsvc_account: "yourdomain\\{{serviceaccount.svcdb.svcname}}"
    mssql_agentsvc_account_pass: "{{serviceaccount.svcdb.svcpassword}}"
    mssql_sqltempDB_filecount: 8
    mssql_sqltempDB_filesize: 8192
    mssql_configuration_option_maxdegreeofparallelism: 4
    mssql_configuration_option_costthresholdforparallelism: 50

invoke-psscript¶

Execute custom PowerShell code or scripts. Specify either script (inline) or path (file on target).

Variable	Required	Type	Description
`script`	Yes (if no `path`)	String	PowerShell script block to execute
`path`	Yes (if no `script`)	String	Path to a PowerShell file on the target host
`parameters`	No	String	JSON string with parameters for the script
`automatic_parameter`	No	Bool	Auto-assign parameters in the script (default: `false`)

Inline script:

- name: invoke-psscript
  variables:
    script: |
      Set-Culture de-CH
      Set-TimeZone -Name "Central Europe Standard Time"

File-based script:

- name: invoke-psscript
  variables:
    path: C:\tools\configure-app.ps1
    parameters: '{"Environment": "Production", "Port": 8080}'

local-group-member¶

Manage local Windows group membership. Both name and members are mandatory.

Variable	Required	Type	Description
`name`	Yes	String	Name of the local group
`members`	Yes	List	Users or groups to add/remove
`state`	No	String	`present` (default) or `absent`

- name: local-group-member
  variables:
    name: Remote Management Users
    members:
      - "yourdomain\\app-team"
      - "yourdomain\\ops-team"

package¶

Install, upgrade, or uninstall software packages. Uses Chocolatey on Windows, the system package manager on Linux.

Variable	Required	Type	Description
`name`	Yes	String or List	Package name(s) to manage
`version`	No	String	Specific version to install (omit for latest)
`state`	No	String	`present` (default), `absent`, or `latest`
`pinned`	No	Bool	Pin the package version (default: `false`)
`force`	No	Bool	Force install/uninstall (default: `false`)
`source`	No	String	Custom Chocolatey source
`package_params`	No	String	Additional package parameters

Single package:

- name: package
  variables:
    name: sql-server-management-studio

Multiple packages:

- name: package
  variables:
    name:
      - pwsh
      - vscode
      - googlechrome
      - firefox

Specific version:

- name: package
  variables:
    name: dotnetcore-windowshosting
    version: 2.1.30

registry-keys¶

Manage Windows registry keys and values.

Variable	Required	Type	Description
`registry_keys`	Yes	List	List of registry key/value definitions

Each item in registry_keys:

Field	Required	Type	Description
`path`	Yes	String	Registry key path (e.g., `HKLM:\Software\MyApp`)
`name`	No	String	Value name (omit to operate on the key itself)
`data`	No	Any	Value data
`type`	No	String	Value type (`string`, `dword`, `binary`, etc.)
`state`	No	String	`present` (default) or `absent`
`delete_key`	No	Bool	Delete the entire key
`hive`	No	String	Registry hive (usually inferred from path)

- name: registry-keys
  variables:
    registry_keys:
      - name: AppSetting
        path: HKLM:\Software\MyApp
        data: production
      - name: MaxConnections
        path: HKLM:\Software\MyApp
        data: 100
        type: dword
      - name: OldSetting
        path: HKLM:\Software\MyApp
        state: absent

request-certificate-acme¶

Request SSL certificates from an ACME server (e.g., Let's Encrypt) using Win-ACME. Both fqdn and email are mandatory.

Variable	Required	Type	Description
`fqdn`	Yes	String	Fully qualified domain name for the certificate
`email`	Yes	String	Email for ACME registration and notifications
`acme_endpoint`	No	String	Custom ACME server endpoint (default: Let's Encrypt production)
`target`	No	String	Set to `iis` to auto-assign to IIS websites

- name: request-certificate-acme
  variables:
    fqdn: "myapp.example.com"
    email: "admin@example.com"
    target: iis

With a custom ACME endpoint:

- name: request-certificate-acme
  variables:
    fqdn: "internal.example.com"
    email: "admin@example.com"
    acme_endpoint: "https://pki.yourdomain.local/acme"

user-rights-assignment¶

Manage Windows user rights assignments (privileges).

Variable	Required	Type	Description
`user_rights`	Yes	List	List of user rights assignments

Each item in user_rights:

Field	Required	Type	Description
`permission`	Yes	String	The privilege (e.g., `SeBatchLogonRight`, `SeLockMemoryPrivilege`)
`identities`	Yes	List/String	Users or groups to assign/remove
`action`	No	String	`add` (default) or `remove`

- name: user-rights-assignment
  variables:
    user_rights:
      - permission: SeLockMemoryPrivilege
        identities:
          - "yourdomain\\{{serviceaccount.svcdb.svcname}}"
      - permission: SeServiceLogonRight
        identities:
          - "yourdomain\\{{serviceaccount.svcdb.svcname}}"

win-feature¶

Install or remove Windows features and roles.

Variable	Required	Type	Description
`name`	Yes	String or List	Feature name(s) to manage
`state`	No	String	`present` (default) or `absent`
`include_management_tools`	No	Bool	Include management tools (default: `false`)
`include_sub_features`	No	Bool	Include sub-features (default: `false`)
`force`	No	Bool	Force install/uninstall (default: `false`)
`source`	No	String	Custom source for feature files

- name: win-feature
  variables:
    name:
      - PowerShell
      - PowerShell-V2
      - WoW64-Support

Remove a feature:

- name: win-feature
  variables:
    name: PowerShell-V2
    state: absent

Next: Expressions