Add a "tags" field to task metadata

[hsnodgrass]

Use Case

When developing Bolt tasks, it would be nice to be able to add arbitrary string tags to tasks for purposes of organization, automation, etc. For example, when writing Bolt tasks that map to compliance rules, it would be nice to be able to add tags with the rule names to the task metadata. These tags wouldn't hold any semantic meaning to Bolt or the task itself, but they would be an easy way for people to identify which tasks map to which compliance rules.

Describe the Solution You Would Like

I would like to see Bolt task metadata support an optional tags field that accepts an array of strings, with no default value. That way, arbitrary tags could be assigned to a task in the metadata like this:

{
  "description": "Some task",
  "input_method": "stdin",
  "tags": [
    "arbitrary_tag1",
    "Arbitrary Tag 2"
  ]
}

Describe Alternatives You've Considered

I'm currently using code comments for this type of information, but those are difficult to parse for automation and differ in style between implementing languages.

[donoghuc]

The task spec is defined in https://github.com/puppetlabs/puppet-specifications/blob/master/tasks/README.md bolt is just one part of the module/task ecosystem. A change like this would be best raised there.

[davidsandilands]

transferring to puppet-specifications as mentioned above

[bastelfreak]

I like this idea and I think it makes sense.

[hsnodgrass]

Opened #161 to address this.

[donoghuc]

How is this meant to be consumed? Would a task runner be expected to surface this information in every place description is currently surfaced? Is a task runner responsible for providing this context when running a task?

[hsnodgrass]

My thought was that is up to the individual task runner if they want to implement special handling for these tags. My personal use case is to query the tags from the metadata files with my own tooling to help generate documentation. I just want a tags key to be recognized as valid in a Task metadata file when it comes to linting, validation, etc.

[donoghuc]

What is preventing you from doing that today? Is there a schema check in a task runner or part of the module ecosystem that is complaining about the addition?

[hsnodgrass]

In my team's workflow, as far as I'm aware, there aren't any checks against the metadata schema. However, because we end up shipping the tasks to our customers as part of the SCE modules, I'd prefer to only use officially documented parameters in the metadata. I don't know what kind of validation workflows customers might have, and I don't want the potential of a support ticket coming in because we added an arbitrary key to task metadata. Admittedly, the chances of that happening are low, but it also seems like the cost of adding a tags key to the metadata schema is low as well.

[hsnodgrass]

After testing adding the tags key to the metadata of a task, bolt task show <task name> does actually return a warning about it:

Metadata for task 'sce_linux::audit_approved_services_listening' contains unknown keys: tags. This could be a typo in the task metadata or might result in incorrect behavior. [ID: unknown_task_metadata_keys]
sce_linux::audit_approved_services_listening
  Report only approved services are listening on a network interface

Usage
  bolt task run sce_linux::audit_approved_services_listening --targets <targets>

Module
  /Users/heston.snodgrass/Documents/repos/puppetlabs-sce_linux

[donoghuc]

Thanks for the context. With this information I wonder if we should be a bit more general. Perhaps a new key (itentifiers?) that points to a map with arbitrary keys.

{
  "description": "Some task",
  "input_method": "stdin",
  "identifiers": {
      "tags": ["whatver", "you", "want"],
      "labels": ["something", "else"]
   }
}

This schema would allow people to essentially have a flexible alternative to the "description" field to to work with that points to maps with whatever structured data they want so they are not confined to just a string. That way we dont have to try to distinguish "version" from "tags" or worry about people wanting some other identifier.

[hsnodgrass]

I like that idea. I'll update #161 for identifiers.

[donoghuc]

Thanks!