Documentation: Plugin module addressing

[independentid]

I had substantial difficulty figuring out how terraform locates plugin and understanding "Address" in ServeOpts works in plugin discovery and initialization.

The relationship between the top-level project (e.g. github project name), the ServeOpts address, and the go modules were unclear in the documentation and tutorial. For example when building the project, if the last plugin name is "abc", then terraform seems to look for: terraform-provider-abc in the go bin directory (apparently requiring the GO project to be called terraform-provider-abc) and the last segment of the Address needs to be "abc".

The server opts address value in main.go, .terraformrc, and project name need to "align" (but not equal).

This was difficult because the current hashicups example tutorial does not use the current plugin framework scaffolding and uses a different plugin start procedure avoiding the ServeOpts Address value.

Hashicups:

func main() {
	tfsdk.Serve(context.Background(), hashicups.New, tfsdk.ServeOpts{
		Name: "hashicups",
	})
}

Plugin Scaffolding Framework:

func main() {
	var debug bool

	flag.BoolVar(&debug, "debug", false, "set to true to run the provider with support for debuggers like delve")
	flag.Parse()

	opts := providerserver.ServeOpts{
		// TODO: Update this string with the published name of your provider.
		Address: "registry.terraform.io/hashicorp/scaffolding",
		Debug:   debug,
	}

	err := providerserver.Serve(context.Background(), provider.New(version), opts)

	if err != nil {
		log.Fatal(err.Error())
	}
}

[bflad]

Hi @independentid 👋 Are you still having trouble with this?

The code in the hashicups-pf provider has since been upgraded to providerserver.ServeOpts, e.g.

https://github.com/hashicorp/terraform-provider-hashicups-pf/blob/12e9150e4df62eb6f86dd074936f2c6155865ce5/main.go#L14-L21

The full address is required because it gets mapped to the TF_REATTACH_CONFIG environment variable when starting up providers in debug mode. Most providers tend to use provider names without dashes after the terraform-provider- conventional prefix, which simplifies things between running go build or go install without special flags. In general and if possible, that is typically the recommendation, however with these two providers they were written as a "new" version of the existing scaffolding/hashicups providers, so they wound up with the extra suffixes.

[independentid]

I found out later (can't remember the issue), that this issue arrises when there is a dash/underscore in the organization name.

For example:
"hashicorp.com/university-edu/hashicups-pf"
Will not be handled correctly.

I incorrectly had concluded the issue was related to how packages names and go module names needed to align. It turns out that too was just another issue.

When I switched to universityedu as org name the problem went away.

[bflad]

@independentid thank you for that additional context. Can you recall what exactly didn't work with provider addresses with dashes/underscores in the namespace? e.g. running the provider locally with a dev_overrides configuration, running the provider locally in debug mode, a Registry issue, etc. I'm just trying to determine if there is something to do in this codebase, improve/fix the framework/Terraform/Registry, or update documentation somewhere. Thanks!

[independentid]

I found I could use dev overrides to get compile and packaging to work. However tests will not run until dash removed from organization name. Hope that helps. I have noticed in general that dashes and underscores in terraform cause a lot of unexpected problems in various parts of terraform. I tend to avoid them everywhere now. Phil

…

On Oct 5, 2022, at 9:38 AM, Brian Flad ***@***.***> wrote:  @independentid thank you for that additional context. Can you recall what exactly didn't work with provider addresses with dashes/underscores in the namespace? e.g. running the provider locally with a dev_overrides configuration, running the provider locally in debug mode, a Registry issue, etc. I'm just trying to determine if there is something to do in this codebase, improve/fix the framework/Terraform/Registry, or update documentation somewhere. Thanks! — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[bflad]

However tests will not run until dash removed from organization name.

Ah ha! Thank you for the clue there. I will create a terraform-plugin-sdk GitHub issue to investigate that further.

I have noticed in general that dashes and underscores in terraform cause a lot of unexpected problems in various parts of terraform. I tend to avoid them everywhere now.

Unfortunately, that does tend to be the case depending on the Terraform component involved since many things have conventionally not included them, but there is also not much feedback from core or the provider frameworks about potential issues when they are used. It'd be great to start patching up non-compliant components or enforce validation against it if necessary.

---

Since I'm not sure there's anything specific to do in this repository, I'm going to close this particular issue for now. If you have specific feedback about a specific component (hashicorp/terraform, hashicorp/terraform-plugin-framework, etc.), we would love to hear about that in a GitHub issue in the relevant repository. Thank you again for the report and sorry for the trouble it caused you in the past.

[bflad]

Acceptance testing issue created: hashicorp/terraform-plugin-sdk#1075

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.