This documentation is for Octopus Deploy Version 3.12. View other versions

Machine Roles

Last updated

Machine roles allow you to “tag” machines with a specific keyword which you can later on use to scope deployment steps and/or variables.

Creating a role and assigning it to a Tentacle

Roles are created and saved in the database the moment you assign them to a Tentacle. To do so, just:

  1. Register a Tentacle or click on an already registered Tentacle and go to Settings.

  2. On the Roles field, type in a single word without spaces and hit enter. This word will be the role name.

  3. Save the Tentacle settings.

Once this is done, the role will not only be assigned to that Tentacle, but it will also be available to be added to all the other Tentacles.

On the screenshot below we've created a role called WebServer and assigned it to our Tentacle Server02.

You can check all the roles assigned to your machines from the Environmentsscreen

Using roles on deployment steps

Almost all the steps that run on a Tentacle can be scoped to one or more roles. This means that the step will only execute on Tentacles with at least one of those roles. This does not mean that if the step is scoped to multiple roles that it will run for each role. Instead it will run that step for all machines that have any roles that match any of the step roles.

To scope a step to a specific role, all you have to do is type in the role name on the Machine Roles field.

After you save the step, all the roles you’ve scoped it for can be viewed from the Deployment Process screen:

According to the screenshot above, our deployment process will do the following:

  • Deploy NuGet package OctoFX.Database to deployment targets with the role app-server
  • Deploy NuGet package OctoFX.RateService to deployment targets with the role web-server

Using roles with variables

Variables can also be scoped to specific roles. This means that the variable will take the specified value only when it is used on a deployment step that runs on a Tentacle with the specified role. This feature can be really handy when you want to use the same variable name multiple times and have their values changed depending on the Tentacle they are running on.

Let’s say you have the following Tentacles with their respective roles:

Tentacle Role
Tentacle 1 app-server
Tentacle 2 web-server

You want to deploy the same package on each server but the deployment path will be different between servers. In this case you can set the same variables (we’ll call it DeployPath) with a different value for each machine role:

Then, on your deployment step, you can set the Custom Install Directory to #{DeployPath} on each of the 3 steps (one for each package Id & Role).

Being smart with Machine Roles
By definition, a role is "the function assumed by a thing in a particular situation". Roles are not Environments or OS versions. Try to use roles to tag servers by their utility and watch out if you find yourself putting more than 3 roles on the same server.