Tags¶

Tags let you plan, apply or check part of a recipe: only nginx's configuration, only the database role, everything but the slow package installs. Give resources tags:, or tag everything an included file declares, then run with --tags or --skip-tags.

New in 0.4.0

Minimal example¶

package "nginx", tags: [:nginx]
file "/etc/nginx/conf.d/app.conf", template: "app.conf.erb", tags: [:nginx, :config]

sudo sadame apply --tags config        # only the configuration file

Tagging¶

Where	Example	Tags
a resource	`package "nginx", tags: [:web]`	`web`
one tag	`user "deploy", tags: :users`	`users`
an included file	`include_recipe "roles/web", tags: [:web]`	`web` on every resource `roles/web.rb` declares, and on the files it includes

Tags are Symbols or Strings without commas or spaces. A resource has its own tags and those of every include_recipe it came through.

Running part of a recipe¶

Option	Runs
`--tags web,db`	only resources with at least one of these tags
`--skip-tags slow`	every resource except those with one of these tags
both	resources with one of the `--tags`, minus those with one of the `--skip-tags`

Both work with plan, apply and drift, locally and on remote hosts. The resources left out are not read or changed, and do not appear in the report; the header says how many were selected, and JSON reports list the tags under tags and skip_tags.

examples/08-multi-role-inventory tags each role:

examples/08-multi-role-inventory/site.rb

# Every host gets the base below; the roles follow the host's groups in
# hosts.rb. Run it on all of them with: sadame apply site.rb -g all
file "/etc/motd", template: "motd.erb", locals: { name: host_name, groups: host_groups }

# Each role's resources are tagged with the role, so --tags web plans or
# applies only the web role, without the base.
include_recipe "roles/web", tags: [:web] if host_groups.include?(:web)
include_recipe "roles/db", tags: [:db] if host_groups.include?(:db)

so the web role can be planned on its own:

$ sadame plan site.rb -g web --tags web
[web1.example.com] sadame 0.5.1 plan on web1.example.com (Debian GNU/Linux 12 (bookworm))
[web1.example.com] Only resources tagged web: 5 of 6.
[web1.example.com]
[web2.example.com] sadame 0.5.1 plan on web2.example.com (Debian GNU/Linux 12 (bookworm))
[web2.example.com] Only resources tagged web: 5 of 6.
[web2.example.com]
[web2.example.com] ~ file[/etc/demo-app/web.conf]
[web2.example.com]     --- /etc/demo-app/web.conf
[web2.example.com]     +++ /etc/demo-app/web.conf (desired)
[web2.example.com]     @@ -1,3 +1,3 @@
[web2.example.com]      # Managed by sadame.
[web2.example.com]      environment = production
[web2.example.com]     -workers     = 12
[web2.example.com]     +workers     = 8
[web2.example.com]
[web1.example.com] Plan: 0 to create, 0 to update, 0 to remove, 0 to run, 5 unchanged.
[web2.example.com] Plan: 0 to create, 1 to update, 0 to remove, 0 to run, 4 unchanged.

Hosts
  web1.example.com  ok
  web2.example.com  ok

plan on 2 hosts: 2 ok. Finished in 0.22s.

Notifications¶

A notification runs even when its target is not selected. With --tags config, a configuration file that changes still reloads the service it notifies, though the service itself is not checked: the reload is part of changing the file.

Common mistakes¶

Expecting untagged resources to run. With --tags, a resource without tags is never selected; that includes base resources such as the login banner above. Tag what belongs to a role, and use --skip-tags when you want everything but something.
Drift with tags. drift --tags web checks only the web resources. Keep the scheduled drift check without tags, so it covers everything.
A tag that matches nothing. sadame does not treat that as an error, because a tag can exist on some hosts and not on others. The header shows "0 of N"; check the spelling when you see it.
Including a file twice with different tags. A file is evaluated once, the first time it is included; later include_recipe calls and their tags are ignored.