Skip to main content
Version: 7.x

Selector

Deployer uses the selector to choose hosts. Each host can have a set of labels. Labels are key-value pairs.

For example, stage: production or role: web.

You can use labels to select hosts. For example, dep deploy stage=production will deploy to all hosts with stage: production label.

Let's define two labels, type and env, to our hosts:

host('web.example.com')
->setLabels([
'type' => 'web',
'env' => 'prod',
]);

host('db.example.com')
->setLabels([
'type' => 'db',
'env' => 'prod',
]);

Now let's define a task to check labels:

task('info', function () {
writeln('type:' . get('labels')['type'] . ' env:' . get('labels')['env']);
});

Now we can run this task with a selector:

$ dep info env=prod
task info
[web.example.com] type:web env:prod
[db.example.com] type:db env:prod

As you can see, Deployer will run this task on all hosts with the env: prod label. And if we define only the type label, Deployer will run this task on the specified host.

dep info type=web
task info
[web.example.com] type:web env:prod

Selector syntax

Label syntax is represented by disjunctive normal form (OR of ANDs).

For example, type=web,env=prod is a selector of: type=web OR env=prod.

$ dep info 'type=web,env=prod'
task info
[web.example.com] type:web env:prod
[db.example.com] type:db env:prod

As you can see, both hosts are selected (as both of them have the env: prod label).

We can use & to define AND. For example, type=web & env=prod is a selector for hosts with type: web AND env: prod labels.

$ dep info 'type=web & env=prod'
task info
[web.example.com] type:web env:prod

We can also use != to negate a label. For example, type!=web is a selector for all hosts which do not have a type: web label.

$ dep info 'type!=web'
task info
[db.example.com] type:db env:prod
note

Deployer CLI can take a few selectors as arguments. For example, dep info type=web env=prod is the same as dep info 'type=web,env=prod'.

You can install bash autocompletion for Deployer CLI, which will help you to write selectors. See installation for more.

Deployer also has a few special selectors:

  • all - select all hosts
  • alias=... - select host by alias

If a selector does not contain an = sign, Deployer will assume that it is an alias.

For example dep info web.example.com is the same as dep info alias=web.example.com.

$ dep info web.example.com
task info
[web.example.com] type:web env:prod
$ dep info 'web.example.com' 'db.example.com'
$ # Same as:
$ dep info 'alias=web.example.com,alias=db.example.com'

Using the select() function

You can use the select() function to select hosts by selector in your PHP code.

task('info', function () {
$hosts = select('type=web,env=prod');
foreach ($hosts as $host) {
writeln('type:' . $host->get('labels')['type'] . ' env:' . $host->get('labels')['env']);
}
});

Or you can use the on() function to run a task on selected hosts.

task('info', function () {
on(select('all'), function () {
writeln('type:' . get('labels')['type'] . ' env:' . get('labels')['env']);
});
});

Task selectors

To restrict a task to run only on selected hosts, you can use the select() method.

task('info', function () {
// ...
})->select('type=web,env=prod');

Labels in YAML

You can also define labels in a YAML recipe. For example:

hosts:
web.example.com:
remote_user: deployer
env:
environment: production
labels:
env: prod

But make sure to distinguish between the env and labels.env keys. env is a configuration key, and labels.env is a label.

task('info', function () {
writeln('env:' . get('env')['environment'] . ' labels.env:' . get('labels')['env']);
});

Will print:

$ dep info env=prod
task info
[web.example.com] env:production labels.env:prod