Deployment Plans

Deployment Plans

Summary

Chocolatey Central Management (CCM) now (in version 0.11.0 and up) supports importing and exporting Deployment Plans. We have several example Deployment Plans that you can import and use immediately, to help you make best use of your Chocolatey for Business suite!

Importing a Deployment Plan

A Deployment Plan can be imported using a .json file.

  1. Prepare your .json file or export an existing Deployment Plan.

  2. From the Chocolatey Central Management dashboard, select Deployment Plans from the left sidebar.

    Chocolatey Central Management dashboard, arrow pointing to Deployment Plans menu in the left sidebar

  3. Select the Import Deployment Plan button at the top of the page.

    Chocolatey Central Management Deployment Plans page, arrow pointing to Import Deployment Plan button

  4. Click the Choose File button to select your .json file. Review the imported Deployment Plan and then click the Import button.

    Chocolatey Central Management import Deployment Plan modal, arrow pointing to the Choose Deployment Plan button and the Import button

    • The Deployment Plan name is shown along with all Deployment Steps after choosing a .json file.
    • A yellow badge will appear next to any Deployment Steps that are privileged, along with a warning that gives more information.

  5. Once the Deployment Plan has been successfully created, you will be taken to the edit page ready to make any additional required changes.

Updating Values in Deployment Plans

When importing an example Deployment Plan, you may have to update the Target Group(s) and any Deployment Start Time that are set.

After importing the Deployment Plan, you should follow these steps to ensure you are able to deploy it!

Setting the Target Group(s)

You will also need to set a Target Group for the Deployment Step:

  • Mouse-over the Deployment Step and click the Edit button. Editing a Deployment Step

  • Navigate to the Select Target Groups panel.

  • Highlight your preferred groups and click the > button to move them into Selected Groups. Selecting Target Groups

  • Click Save.

Setting the Start Time Date (Scheduled Deployments)

Before you can run the Deployment Plan, you must set the Start Date Time to a time at least 30 minutes in the future.

To do so, click on the clock icon next to the Start Date Time field. When you have selected an appropriate time, click Save.

Updating an invalid Start Date Time

Example Deployment Plans

We have several example Deployment Plans shown below, and you can check the Chocolatey Central Management Deployment Plan Examples repository on GitHub for more.

Installing or Upgrading a Package

The only Deployment Step in this Deployment Plan upgrades, or installs if not present, the Firefox package (available on the Chocolatey Community Repository).

Assuming this package was available on your sources, you will only need to set the Target Groups for the Deployment Step. If you don't have it available, you can download it using choco download firefox --source="'https://community.chocolatey.org/api/v2/'" and then upload it to your internal repository.

Save the following as a .json file to import as a Chocolatey Central Management Deployment Plan:

{
  "Name": "Installing a Package (Simple)",
  "ScheduledDateTimeUtc": null,
  "LastScheduledDateTimeUtc": null,
  "RepeatPeriod": 0,
  "ExecutionTimeoutInSeconds": 14400,
  "RequiresApproval": false,
  "DeploymentSteps": [
    {
      "Name": "Deploy Firefox",
      "IsPrivileged": false,
      "PlanOrder": 1,
      "Script": "upgrade|firefox||false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    }
  ]
}

Installing Multiple Packages

This Deployment Plan is a basic example of deploying multiple packages.

We recommend that you use a separate Deployment Step for each package to deploy to allow per-computer reporting.

You can use this to generate larger Deployment Plans with more comprehensive suites of packages, even mixing Basic and Advanced Deployment Steps in order to provide additional configuration.

Save the following as a .json file to import as a Chocolatey Central Management Deployment Plan:

{
  "Name": "Deploying Multiple Packages",
  "ScheduledDateTimeUtc": null,
  "LastScheduledDateTimeUtc": null,
  "RepeatPeriod": 0,
  "ExecutionTimeoutInSeconds": 14400,
  "RequiresApproval": false,
  "DeploymentSteps": [
    {
      "Name": "Deploy Cloudflared",
      "IsPrivileged": false,
      "PlanOrder": 1,
      "Script": "upgrade|cloudflared||false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    },
    {
      "Name": "Deploy Firefox",
      "IsPrivileged": false,
      "PlanOrder": 2,
      "Script": "upgrade|firefox||false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    },
    {
      "Name": "Deploy VSCode",
      "IsPrivileged": false,
      "PlanOrder": 3,
      "Script": "upgrade|vscode||false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    },
    {
      "Name": "Deploy 7zip",
      "IsPrivileged": false,
      "PlanOrder": 4,
      "Script": "upgrade|7zip||false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    }
  ]
}

Installing a Package with Parameters

This Deployment Plan is an example of deploying a package using an Advanced Deployment Step, in this case to provide a package parameter during deployment.

The example passes the /InstallDir parameter to the python312 package, causing the package to be installed to the location provided.

We use the Advanced Deployment Step to do this because the Basic Deployment Step does not allow package parameters to be used.

Save the following as a .json file to import as a Chocolatey Central Management Deployment Plan:

{
  "Name": "Deployment Plan with Parameters",
  "ScheduledDateTimeUtc": null,
  "LastScheduledDateTimeUtc": null,
  "RepeatPeriod": 0,
  "ExecutionTimeoutInSeconds": 14400,
  "RequiresApproval": false,
  "DeploymentSteps": [
    {
      "Name": "Deploy Python to Agent Directory",
      "IsPrivileged": true,
      "PlanOrder": 1,
      "Script": "choco install python312 --package-parameters=\"'/InstallDir:C:\\BuildAgent\\tools\\python312'\"\nexit $LASTEXITCODE",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    }
  ]
}

Advanced Deployments

Using a Deployment Schedule

The following Deployment Plan maintains your Chocolatey license in your environment. It assumes that as a Chocolatey for Business customer you have created a chocolatey-license package. If you don't currently have a license package, you can create one by following the instructions.

The Deployment Step included in this Deployment Plan upgrades, or installs if not present, the chocolatey.license package. The Deployment Plan utilizes a schedule which will execute daily.

Save the following as a .json file to import as a Chocolatey Central Management Deployment Plan:

{
  "Name": "Upgrade License (Daily)",
  "ScheduledDateTimeUtc": "2023-01-01T00:00:00Z",
  "LastScheduledDateTimeUtc": null,
  "RepeatPeriod": 1,
  "ExecutionTimeoutInSeconds": 14400,
  "RequiresApproval": false,
  "DeploymentSteps": [
    {
      "Name": "Update License",
      "IsPrivileged": false,
      "PlanOrder": 1,
      "Script": "upgrade|chocolatey.license||false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    }
  ]
}

A weekly version of this Deployment Plan is available. Click the button below and save the following as a .json file to import as a Chocolatey Central Management Deployment Plan:

{
  "Name": "Upgrade License (Weekly)",
  "ScheduledDateTimeUtc": "2023-01-01T00:00:00Z",
  "LastScheduledDateTimeUtc": null,
  "RepeatPeriod": 2,
  "ExecutionTimeoutInSeconds": 14400,
  "RequiresApproval": false,
  "DeploymentSteps": [
    {
      "Name": "Update License",
      "IsPrivileged": false,
      "PlanOrder": 1,
      "Script": "upgrade|chocolatey.license||false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    }
  ]
}

Upgrading Chocolatey for Business Client Packages

These Deployment Plans are examples of upgrading the Chocolatey for Business client packages.

There are two example Deployment Plans here. They follow the instructions laid out on the upgrading to Chocolatey v2 page.

Upgrade the Chocolatey for Business Client Packages to the Latest 1.x Version.

Save the following as a .json file to import as a Chocolatey Central Management Deployment Plan:

{
  "Name": "Upgrade Chocolatey for Business Client to Latest 1.x",
  "ScheduledDateTimeUtc": null,
  "LastScheduledDateTimeUtc": null,
  "RepeatPeriod": 0,
  "ExecutionTimeoutInSeconds": 14400,
  "RequiresApproval": false,
  "DeploymentSteps": [
    {
      "Name": "Upgrade to Latest 1.x Client Components",
      "IsPrivileged": true,
      "PlanOrder": 1,
      "Script": "$Installed = choco list --local-only --limit-output | ConvertFrom-Csv -Delimiter '|' -Header 'Id','Version'\n$ChocolateyVersion = $Installed.Where{$_.Id -eq 'chocolatey'}.Version\n$AgentVersion = $Installed.Where{$_.Id -eq 'chocolatey-agent'}.Version\n$ExtensionVersion = $Installed.Where{$_.Id -eq 'chocolatey.extension'}.Version\n# We don't need to run this step if we're already on the latest 1.*\nif ([version]$ChocolateyVersion -ge '1.4.0' -and [version]$AgentVersion -ge '1.1.2' -and [version]$ExtensionVersion -ge '5.0.3') {\n    exit 0\n}\n\n$delayInMinutes = 1\n# If using an internal repository to install Chocolatey Agent, replace `chocolatey.licensed` below\n# with the name or URL of your internally configured source.\nchoco upgrade chocolatey-agent --version=1.1.2 --source=\"'chocolatey.licensed'\"\n\n# Ensure the deployment task registers as failed if the installation failed, and skip registering the\n# scheduled task.\nif ($LASTEXITCODE -ne 0) {\n    Write-Error 'The upgrade failed!'\n    exit $LASTEXITCODE\n}\n\n# Restart the Agent service after the preset delay time via a scheduled task.\n$ScheduledTask = @{\n    TaskName = \"Restart chocolatey-agent\"\n    Description = \"Upgrade Chocolatey Agent\"\n    Trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes)\n    Action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument \"-WindowStyle Hidden -Command Restart-Service chocolatey-agent\"\n    Principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest\n    Settings = New-ScheduledTaskSettingsSet -Hidden\n}\n\nRegister-ScheduledTask @ScheduledTask -Verbose:$false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    },
    {
      "Name": "Ensure Chocolatey CLI 1.4.0",
      "IsPrivileged": true,
      "PlanOrder": 2,
      "Script": "choco upgrade chocolatey --version=1.4.0 --source=\"'chocolatey.licensed'\"\nexit $LASTEXITCODE",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    }
  ]
}
Upgrade the Chocolatey for Business Client Packages to the Latest Version.

Save the following as a .json file to import as a Chocolatey Central Management Deployment Plan:

{
  "Name": "Upgrade Chocolatey for Business Client",
  "ScheduledDateTimeUtc": null,
  "LastScheduledDateTimeUtc": null,
  "RepeatPeriod": 0,
  "ExecutionTimeoutInSeconds": 14400,
  "RequiresApproval": false,
  "DeploymentSteps": [
    {
      "Name": "Upgrade Chocolatey for Business Client Components",
      "IsPrivileged": true,
      "PlanOrder": 1,
      "Script": "$delayInMinutes = 1\n\n# If using an internal repository to install Chocolatey Agent, replace `chocolatey.licensed` below\n# with the name or URL of your internally configured source.\nchoco upgrade chocolatey-agent --source=\"'chocolatey.licensed'\"\n\n# Ensure the deployment task registers as failed if the installation failed, and skip registering the\n# scheduled task.\nif ($LASTEXITCODE -ne 0) {\n    Write-Error 'The upgrade failed!'\n    exit $LASTEXITCODE\n}\n\n# Restart the Agent service after the preset delay time via a scheduled task.\n$ScheduledTask = @{\n    TaskName = \"restart chocolatey-agent\"\n    Description = \"Upgrade Chocolatey Agent\"\n    Trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes($delayInMinutes)\n    Action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument \"-WindowStyle Hidden -Command Restart-Service chocolatey-agent\"\n    Principal = New-ScheduledTaskPrincipal -GroupId Administrators -RunLevel Highest\n    Settings = New-ScheduledTaskSettingsSet -Hidden\n}\nRegister-ScheduledTask @ScheduledTask -Verbose:$false",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    },
    {
      "Name": "Ensure Chocolatey CLI is Upgraded",
      "IsPrivileged": true,
      "PlanOrder": 2,
      "Script": "choco upgrade chocolatey --source=\"'chocolatey.licensed'\"\nexit $LASTEXITCODE",
      "ValidExitCodes": "0, 1605, 1614, 1641, 3010",
      "ExecutionTimeoutInSeconds": 14400,
      "FailOnError": true,
      "RequireSuccessOnAllComputers": false,
      "MachineContactTimeoutInMinutes": 0,
      "DeploymentStepGroupIds": []
    }
  ]
}