Automation with Octopus.Client

At Octopus Deploy we keep rattling on about how Octopus is API first. One of the benefits of being API first is that you can do anything that the Octopus UI does via web requests. We have a handy library called Octopus.Client that wraps the API and makes it easy to perform operations on your Octopus Deploy Server. This article will focus on some common operations using PowerShell.

Getting Started

There are many ways to get your hands on Octopus.Client. There is a NuGet package that you can include in your Visual Studio projects and Octopus.Client is available from the Octopus Server and Tentacle installation folders.

To get started in PowerShell you will need to reference the Octopus.Client dll:

Add-Type -Path 'Octopus.Client.dll'

To perform an operation on the Octopus Server you will need to create a connection to the Octopus Server using an API key:

$octopusURI = "http://localhost"
$apiKey = 'API-ALLYOURBASEBELONGTOUS'
$endpoint = new-object Octopus.Client.OctopusServerEndpoint $octopusURI, $apiKey 

And finally, use the connection to access the Octopus Server repository:

$repository = new-object Octopus.Client.OctopusRepository $endpoint

Simple Operations

Most of the resources in your Octopus Server can be accessed via Octopus.Client through a common set of operations:

• FindAll()
• Get(id)
• Create(resource)
• Modify(resource)
• Delete(resource)

For example, to create an environment:

Add-Type -Path 'Octopus.Client.dll'

$octopusURI = "http://localhost"
$apiKey = 'API-ALLYOURBASEBELONGTOUS'

$endpoint = new-object Octopus.Client.OctopusServerEndpoint $octopusURI, $apiKey 
$repository = new-object Octopus.Client.OctopusRepository $endpoint

$environment = new-object Octopus.Client.Model.EnvironmentResource
$environment.Name = "Demo environment"
$environment.Description = "An environment for demonstrating Octopus.Client"

$repository.Environments.Create($environment)

Automating all the things

The real power of Octopus.Client is the ability to automate. For example: you could provision a bunch of Tentacles, add them to an environment and then deploy the latest release of all of your projects to that environment by pushing a bunch of buttons in the Octopus UI OR you could write a script.

Adding a listening Tentacle to an environment:

Add-Type -Path 'Octopus.Client.dll'

$octopusURI = "http://localhost"
$apiKey = 'API-ALLYOURBASEBELONGTOUS'

$endpoint = new-object Octopus.Client.OctopusServerEndpoint $octopusURI, $apiKey 
$repository = new-object Octopus.Client.OctopusRepository $endpoint

$tentacleEndpoint = New-Object Octopus.Client.Model.EndPoints.ListeningTentacleEndpointResource
$tentacleEndpoint.Thumbprint = "B0EDD32958AC90743F21F96DD9AAD5E13AF202EF"
$tentacleEndpoint.Uri = "https://localhost:10933"

$environment = $repository.Environments.FindByName("Demo environment")

$tentacle = New-Object Octopus.Client.Model.MachineResource
$tentacle.Endpoint = $tentacleEndpoint
$tentacle.EnvironmentIds.Add($environment.Id)
$tentacle.Roles.Add("demo-role")
$tentacle.Name = "Demo Tentacle"

$repository.Machines.Create($tentacle)

Deploying a release from each project to an environment:

Add-Type -Path 'Octopus.Client.dll'

$octopusURI = "http://localhost"
$apiKey = 'API-ALLYOURBASEBELONGTOUS'

$endpoint = new-object Octopus.Client.OctopusServerEndpoint $octopusURI, $apiKey 
$repository = new-object Octopus.Client.OctopusRepository $endpoint

$environment = $repository.Environments.FindByName("Demo environment")

$projects = $repository.Projects.FindAll()
foreach ($project in $projects)
{
    $releases = $repository.Projects.GetReleases($project)
    $latestRelease = $releases.Items | Select-Object -first 1
    $deployment = new-object Octopus.Client.Model.DeploymentResource
    $deployment.ReleaseId = $latestRelease.Id
    $deployment.EnvironmentId = $environment.Id
    $repository.Deployments.Create($deployment)
}

With a bit of creativity you could automate your deployment automation system and integrate with your favorite tools.

Troubleshooting

The Octopus Server API is a good place to start to learn more about the available resources and how they are structured. It is available by browsing to /api on your Octopus Server. Watching Fiddler while using Octopus Server through the web interface can help understand more complex resource interactions, such as creating variable sets and deployment processes. Finally, I find exploring the intellisense in Visual Studio and PowerShell ISE helps build familiarity with the methods and properties available from Octopus.Client (and by extension, the API).

Happy automations!