Docs: Usage of defaultTags is not especially clear

[jkodroff]

When using defaultTags for the first time in the AWS Provider, I I found the docs on how to configure defaultTags to be a little confusing. If you look at the screenshot below, it wasn't especially clear how to set this via pulumi config set or how to enter it in Pulumi.stack.yaml manually due to the use of the words "JSON block" and also how "Tags" appears below the option when "Tags" is really the value of the setting itself.

Not entirely sure what tools we have at our disposal to improve. Could be overriding the docs, or could be a change to how we generate the docs, or could be just adding an example that shows its usage.

FWIW, I ended up adding the config manually to Pulumi.dev.yaml like so:

config:
  aws:defaultTags:
    tags:
      owner: platform-integrations
      repo: pulumi/github-issue-automation

[ringods]

@cnunciato I lost a few hours on this myself today. Is there anything we can do in making this more clear in our docs?

[t0yv0]

Greetings, can I assist here? Recent version of the provider went to great lengths to make the default tagging feature work well. We need to tell the story of how to use it. Can I put a PR here that lifts the defaultTags docs to markdown file you can further edit? I'd really appreciate help with getting the copy right as it is not my forte.

[vipetrul]

In my case I needed to create default tags when using Pulumi Automation API. There was no physical Pulumi.<env>.yaml to work with, but I was able to achieve the same functionality using code:

await stack.setConfig('aws:defaultTags', {
      value: JSON.stringify({
        tags: {
          keyOne: 'valueOne',
          keyTwo: 'valueTwo',
        },
      }),
    });

Would be great to include this in documentation as well.

[cnunciato]

These docs are actually hand-crafted and located in the pulumi/registry repo. We can correct them there. Transferring the issue to that repo and we'll get it onto the Docs board.

[mattfysh]

how can this be set from the CLI? the only command I could get to work:

> pulumi config set --path 'aws:defaultTags.tags' '{"user:Project": "my_project"}'

but the program failed to run:

error: pulumi:providers:aws resource 'default_6_9_0' has a problem: could not validate provider configuration: Attribute must be a map. Check `pulumi config get --path aws:defaultTags.tags`

other things I've tried:

> pulumi config set --path 'aws:defaultTags.tags.["user:Project"]' my_project
error: invalid configuration key: could not parse aws:defaultTags.tags.["user:Project"] as a configuration key (configuration keys should be of the form `<namespace>:<name>`)

> pulumi config set --path 'aws:defaultTags.tags.user:Project' my_project
# same error as above

> pulumi config set --path 'aws:defaultTags.tags.test' true
error: defaultTags.tags: expected a map

[lkolchin]

Same problem here:

$ cat Pulumi.yaml
name: pulumi-ecs-nginx
runtime: nodejs
description: An example of ECS Fargate with Pulumi
config:
  pulumi:tags:
    value:
      pulumi:template: aws-typescript
  aws:defaultTags:
    tags:
      value:
        Project: "pulumi-ecs-nginx"
        TechBrownbag: "true"

Diagnostics:
  pulumi:providers:aws (default_6_29_0):
    error: pulumi:providers:aws resource 'default_6_29_0' has a problem: `aws:defaultTags.project` is not a valid configuration key for the aws provider. If the referenced key is not intended for the provider, please choose a different namespace from `aws:`.
    error: pulumi:providers:aws resource 'default_6_29_0' has a problem: `aws:defaultTags.techBrownbag` is not a valid configuration key for the aws provider. If the referenced key is not intended for the provider, please choose a different namespace from `aws:`.

[ecerulm]

With pulumi 3.129.0

Clear all tags

pulumi config rm --path 'aws:defaultTags'     

Add a tag

pulumi config set --path 'aws:defaultTags.tags.ManagedBy' 'pulumi'

I didn't find a way to add a tag where the name has a colon , it doesn't seem to be any way to escape the colon and cli thinks there can only be a single colon (<namespace>:<name>):

if you you need to add such name you can always edit the Pulumi.xxx.yaml and add it manually

config:
  aws:defaultTags:
    tags:
      ManagedBy: pulumi
      "user:Project": pulumi

[mattfysh]

Sometimes editing the file by hand is not possible, e.g. scripts that create new stacks programatically

[ecerulm]

Sometimes editing the file by hand is not possible, e.g. scripts that create new stacks programatically

I'm not a contributor of this project, but I think the pulumi config set does not support colon : in the tag name (I've opened https://github.com/pulumi/pulumi/issues/17033).

As a workaround you can always edit the file programatically (you don't need to do it manually), instead of using pulumi config set to edit the file you can use yq for example :

yq -i '.config."aws:defaultTags".tags."user:Project" = "my_project"' Pulumi.dev.yaml

the command above set "user:Project" tag in the Pulumi.dev.yaml (dev is the stack name I'm using) , and I see that pulumi reads it ok:

pulumi config get --path 'aws:defaultTags.tags'
{"user:Project":"my_project"}

I agree is less convenient and that why I opened #17033, but I don't think currently a change in the docs (and this issue is about that) can help with the colon in tag name issue. Other than mentioning that is not currently possible, and giving a workaround, that is.

[Sodki]

For me the most confusing thing is that there is a difference between how aws:defaultTags is set at the project level or at the stack level.

At the stack level this works:

aws:defaultTags:
  tags:
    key: value

At the project level, the same fails with the message:

error: could not validate '<redacted>/Pulumi.yaml': 7 errors occurred:
        * #/config/aws:defaultTags: oneOf failed
        * #/config/aws:defaultTags: expected string, but got object
        * #/config/aws:defaultTags: expected integer, but got object
        * #/config/aws:defaultTags: expected boolean, but got object
        * #/config/aws:defaultTags: expected array, but got object
        * #/config/aws:defaultTags: doesn't validate with '/$defs/configTypeDeclaration'
        * #/config/aws:defaultTags: additionalProperties 'tags' not allowed

To make it work at the project level, I have to use:

aws:defaultTags:
  value:
    tags:
      key: value

This is very confusing.

[chrisvander]

@Sodki thanks for your comment. You helped me unravel this mess of formatting.

Why does it behave differently at the project and stack level?

[ringods]

@chrisvander the reason for a different format at project level and stack level is because you can also define the "schema" of your config at the project level. We needed a way to differentiate between the schema and the values.

https://www.pulumi.com/docs/iac/concepts/config/#strongly-typed-configuration

[chrisvander]

Understood. Is that the reason why defining it without the value: key is resulting in that error? Or is it supposed to handle both cases?