Upgrade
Upgrade
Upgrade Process
NOTE
The upgrade of
chocolatey-agent
throughchocolatey-agent
will require a restart of the service in order for the new version to be picked up.
Minor / Patch Versions (for example 1.1.x to 1.3.x, or 1.1.1 to 1.1.5)
To upgrade Chocolatey Agent directly, you can upgrade it through Chocolatey CLI with the command choco upgrade chocolatey-agent
.
Major Versions
When upgrading Chocolatey Agent to a new major version (for example, v1.x to v2.x) a specific upgrade process needs to be followed to ensure that all its dependencies will be correctly installed.
As an example, the upgrade process for v1.x to v2.x is as follows:
- Ensure you are on the latest stable v1.x version of Chocolatey CLI, v5.x version of Chocolatey Licensed Extension, and v1.x version of Chocolatey Agent.
- To find the latest versions, you can use
choco search --exact chocolatey --all-versions
(orchocolatey.extension
/chocolatey.agent
for those packages). You can also visit Chocolatey CLI’s Chocolatey Community Repository page (or other packages’ pages on the site) and look at the Version History section to get this list.
- To find the latest versions, you can use
- Upgrade
chocolatey
first. - Due to the dependency version ranges and Chocolatey CLI’s dependency resolution,
chocolatey-agent
will be upgraded alongside thechocolatey
package and associated dependencies.
Using Chocolatey Central Management to Upgrade chocolatey-agent
Because Chocolatey Central Management uses chocolatey-agent
to perform its actions, the upgrade will require a restart of the service.
The easiest way to do this is with a scheduled task as part of an Advanced Deployment Step.
A recommended Advanced Deployment Step script to do this is as follows:
NOTE
If upgrading
chocolatey-agent
to a new major version, target only thechocolatey
package for thechoco upgrade
command in the script below, instead of thechocolatey-agent
package.
$delayInMinutes = 1
# If using an internal repository to install Chocolatey Agent, replace `chocolatey.licensed` below
# with the name or URL of your internally configured source.
choco upgrade chocolatey-agent --source 'chocolatey.licensed'
# Ensure the deployment task registers as failed if the installation failed, and skip registering the
# scheduled task.
if ($LASTEXITCODE -ne 0) {
Write-Error 'The upgrade failed!'
exit $LASTEXITCODE
}
# Restart the Agent service after the preset delay time via a scheduled task.
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes)
$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument "-WindowStyle Hidden -Command Restart-Service chocolatey-agent"
$principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest
$settings = New-ScheduledTaskSettingsSet -Hidden
Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "restart chocolatey-agent" -Description "Upgrade Chocolatey Agent" -Principal $principal -Settings $settings -Verbose:$false
WARNING
Although the
ScheduledTasks
module is available on Windows Server 2012 R2, thechocolatey-agent
service encounters an error when trying to import it. It is recommended to explore other options for the scheduled task if you’re using Windows Server 2012 R2.
Change Service Account Username or Password
If you need to change the username or password of the Chocolatey Agent, you have a few options:
- Change it through the Windows Service Manager
- Change it during an upgrade by passing the new username/password to the upgrade command
- Change it during an uninstall and reinstall while passing the new username/password to the install command.
WARNING
The service password cannot be changed through a Chocolatey upgrade command while the service is running.
Use Chocolatey Central Management to Change the Service Account Username or Password
If you use Chocolatey Central Management, you won’t be able to use a Deployment Step to uninstall the agent and then install the agent. This is because the agent cannot change the username/password while is it running. Instead, you can send a Deployment Step that creates a scheduled task to uninstall the agent, then install with the new parameters.
NOTE
Due to limitations of Windows Task Scheduler, it is likely that your users will see the PowerShell window initially, but it should disappear once PowerShell has fully started.
An example advanced Deployment Step script to do this is as follows:
$delayInMinutes = 1
$newUsername = '<Username>'
$newPassword = '<Password>'
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes)
$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument "-WindowStyle Hidden -Command choco uninstall chocolatey-agent -y ; choco install chocolatey-agent -y --params='/Username:$newUsername' --package-parameters-sensitive='/Password:$newPassword'"
$principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest
$settings = New-ScheduledTaskSettingsSet -Hidden
Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "Upgrade chocolatey-agent" -Description "Upgrade Chocolatey Agent" -Principal $principal -Settings $settings -Verbose:$false
NOTE
Be sure to use Sensitive Variables to ensure the username and password don’t get added to the Chocolatey logs when using Chocolatey Central Management version 0.7.0 or newer.
WARNING
Although the
ScheduledTasks
module is available on Windows Server 2012 R2, thechocolatey-agent
service encounters an error when trying to import it. It is recommended to explore other options for the scheduled task if you’re using Windows Server 2012 R2.