Search location for Credential Helper executables is now effectively undocumented

[apparentlymart]

Terraform Version

I observed this in the Terraform v1.4.x documentation that was current at the time I opened this issue.

Affected Pages

Credentials Helpers

What is the docs issue?

When this page was originally written there was another page describing in general how Terraform CLI finds plugin executables, which the credentials helper page just linked to as an alternative to duplicating that information.

Unfortunately in the meantime Terraform's treatment of provider plugins has become significantly more sophisticated and complex, and our documentation elsewhere focused on how provider plugins work and no longer talk about the simpler mechanism that Terraform uses to find credentials helpers.

Specifically:

• How Terraform finds Credentials Helpers used to link to general docs about plugin discovery, but that old page was removed in favor of a page in the provider development section.
• The Plugin Locations section on that page just delegates to the CLI configuration docs.
• The Provider Installation instructions on that page are focused only on provider installation and do not discuss credentials helpers at all.
• That page also includes a section on Credentials Helpers, but that just links back to the "internals" page on Credentials Helpers that we started with rather than directly discussing how to install credentials helpers.

Proposal

Credentials helpers are pretty different in practice to provider plugins: they are always installed manually rather than automatically by terraform init, they are simple request-response programs using stdout/stdin rather than running a gRPC server, and they must be explicitly configured in the CLI configuration.

Therefore I suggest that we just remove all of the attempted indirection here and document the installation method for credentials helpers directly on the Credentials Helpers page.

Specifically, I would consider changing the "How Terraform finds Credentials Helpers" section so that it ends by directly describing where Terraform CLI will search to find the credentials helpers:

[...]

A credentials helper called "credstore", for example, would be implemented as an executable program named terraform-credentials-credstore (with an .exe extension on Windows only).

Terraform searches for executables matching that naming scheme in different directories depending on the operating system where you are running Terraform:

• Linux, macOS, and other Unix systems: $HOME/.terraform.d/plugins
• Windows: %APPDATA%\terraform.d\plugins

If you reuse the same home directory across multiple computers with different operating systems or CPU architectures then you can optionally categorize your credentials helpers by target platform by creating platform-specific subdirectories under the directories given above.

For example, if you use the same home directory with both a Linux system using the "amd64" (x86_64) architecture and a system using the "arm64" (AArch64) architecture, you can place their credentials helper executables in $HOME/.terraform.d/plugins/linux_amd64 and $HOME/.terraform.d/plugins/linux_arm64 respectively. Run terraform version to see the appropriate platform name to use for a particular build of Terraform CLI.

The above is the essence of the content that was available on the page that was originally linked from the credentials helpers page when it was first written.

There is another section at the end of the page titled "Installing a credentials helper", which currently also links to the unhelpful loop of pages described above. I'm not sure we really need to separate "How Terraform finds" from "How to install", but if we do intend to keep both sections then we should perhaps make one link to the other within the same page, rather than linking out to external content that is no longer relevant.

[Jagannathmaity110]

Hello I am looking for some good first issue , I am new at open source ,is that good for me?

[crw]

@Jagannathmaity110 No, this needs to be solved internally. The provider teams (e.g. https://hashicorp.github.io/terraform-provider-aws/) are more suited to first issues. Thanks.