non-deterministic behavior in examples docs generation

[jazzyfresh]

What happened?

Running make tfgen on the pulumi-gitlab provider non-deterministically removes & adds an example from the docs generation in the schema

The example for the gitlab.UserGpgKey resource is added/removed from various languages (typescript, python, dotnet, go, yaml, java) on every run.

csharp\nusing System.Collections.Generic;\nusing System.Linq;\nusing Pulumi;\nusing GitLab = Pulumi.GitLab;\n\nreturn await Deployment.RunAsync(() =\u003e \n{\n var exampleUser = GitLab.GetUser.Invoke(new()\n {\n Username = "example-user",\n });\n\n // Manages a GPG key for the specified user. An admin token is required if user_id is specified.\n var exampleUserGpgKey = new GitLab.UserGpgKey("exampleUserGpgKey", new()\n {\n UserId = exampleUser.Apply(getUserResult =\sult.Id),\n Key = @"-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----",\n });\n\ a GPG key for the current user\n var exampleUserUserGpgKey = new GitLab.UserGpgKey("exampleUserUserGpgKey", new()\ Key = @"-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----",\n });\n\n});\n\n

Expected Behavior

make tfgen should be consistent every time!

Steps to reproduce

This behavior was discovered on a branch that added auto-token mapping to the gitlab provider, it may have to do with that.

git clone git@github.com:pulumi/pulumi-gitlab.git
cd pulumi-gitlab
git fetch
git checkout jazzyfresh/auto-token-map
make tfgen    # may need to repeat make tfgen a few times to see the schema change
git status    # you will see the schema.json change
git diff      # you will see only the examples for the UserGpgKey resource being modified

Output of pulumi about

from the pulumi-gitlab/examples directory

Additional context

No response

Contributing

No response

[jazzyfresh]

More debugging notes:

• you can isolate debugging this resource by setting a breakpoint with the conditional
  • name == "#/resources/gitlab:index/userGpgKey:UserGpgKey"
  • at this point in docs gen https://github.com/pulumi/pulumi-terraform-bridge/blob/master/pkg/tfgen/docs.go#L1158
  • and then running the tfgen.Main() method over and over again
• following the stacktrace of the error we get to tf12 which panics silently with a diagnostic that isn't logged anywhere https://github.com/pulumi/pulumi-terraform-bridge/blob/master/pkg/tf2pulumi/convert/tf12.go#L176
  • the diagnostic reports an error at the 12th character of the following string

  • exampleIndex/getUserUser = invoke("gitlab:index/getUser:getUser", {\n username = "example-user"\n})\n# Manages a GPG key for the specified user. An admin token is required if user_id is specified.\nresource exampleUserGpgKey "gitlab:index/userGpgKey:UserGpgKey" {\n userId = exampleIndex/getUserUser.id\n key = "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----"\n}\n# Manages a GPG key for the current user\nresource exampleUser "gitlab:index/userGpgKey:UserGpgKey" {\n key = "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----"\n}

    • it errors at the 12th character, eg the / of exampleIndex/getUserUser
    • you can see that this docs string is rendered incorrectly, it seems to embed Index/getUser into exampleUser which is the actual part of the hcl example
    • the corresponding hcl example https://github.com/gitlabhq/terraform-provider-gitlab/blob/main/docs/resources/user_gpgkey.md#example-usage
• setting various breakpoints in the debugger brought us to this method convertHCLToString() in the tfgen docs file https://github.com/pulumi/pulumi-terraform-bridge/blob/master/pkg/tfgen/docs.go#L1307
  • is it possible we're overwriting the afero cache for this example file?
  • need more insight into how convertHCL is supposed to work

[jazzyfresh]

a similar prior bug #521

[jazzyfresh]

possibly unrelated, but this warning does show up in the output.

warning: unable to convert HCL example for Pulumi entity '#/functions/gitlab:index/getUser:getUser': 6 errors occurred:
	* failed to convert HCL for #/functions/gitlab:index/getUser:getUser to typescript: #-functions-gitlab:index-getUser:getUser.pp:3,37-42: unknown function 'toset'; 
	* failed to convert HCL for #/functions/gitlab:index/getUser:getUser to python: #-functions-gitlab:index-getUser:getUser.pp:3,37-42: unknown function 'toset'; 
	* failed to convert HCL for #/functions/gitlab:index/getUser:getUser to csharp: #-functions-gitlab:index-getUser:getUser.pp:3,37-42: unknown function 'toset'; 
	* failed to convert HCL for #/functions/gitlab:index/getUser:getUser to go: #-functions-gitlab:index-getUser:getUser.pp:3,37-42: unknown function 'toset'; 
	* failed to convert HCL for #/functions/gitlab:index/getUser:getUser to yaml: #-functions-gitlab:index-getUser:getUser.pp:3,37-42: unknown function 'toset'; 
	* failed to convert HCL for #/functions/gitlab:index/getUser:getUser to java: #-functions-gitlab:index-getUser:getUser.pp:3,37-42: unknown function 'toset';

no warnings are logged for userGpgKey however

[jazzyfresh]

looking more closely at the rendered string above in and comparing it to the original hcl example

• data "gitlab_user" "example" =>
  exampleIndex/getUserUser = invoke("gitlab:index/getUser:getUser",
• resource "gitlab_user_gpgkey" "example" =>
  resource exampleUserGpgKey "gitlab:index/userGpgKey:UserGpgKey"
• data.gitlab_user.example.id => exampleIndex/getUserUser.id
• resource "gitlab_user_gpgkey" "example_user" =>
  resource exampleUser "gitlab:index/userGpgKey:UserGpgKey"

everything else is rendered correctly

[iwahbe]

This was closed by #1041.