hashicorp / hashicorp/web-unified-docs

Search location for Credential Helper executables is now effectively undocumented

Open
#754 2 comments 0 reactions 0 assignees View on GitHub
documentation Terraform CE
Dominant language
MDX
Stars
86
Forks
275
Avg merge
3d 18h
Merged PRs (30d)
199

Description

### 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](https://developer.hashicorp.com/terraform/internals/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](https://developer.hashicorp.com/terraform/internals/credentials-helpers#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](https://developer.hashicorp.com/terraform/plugin/how-terraform-works).
* The [Plugin Locations](https://developer.hashicorp.com/terraform/plugin/how-terraform-works#plugin-locations) section on that page just delegates to [the CLI configuration docs](https://developer.hashicorp.com/terraform/cli/config/config-file).
* The [Provider Installation](https://developer.hashicorp.com/terraform/cli/config/config-file#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](https://developer.hashicorp.com/terraform/cli/config/config-file#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](https://developer.hashicorp.com/terraform/internals/credentials-helpers).

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.

Contributor guide

Open the contributing guide

Research direction

Start with the Credentials Helpers page, especially “How Terraform finds Credentials Helpers” and “Installing a credentials helper,” then compare the linked plugin-location and CLI configuration pages. Document the operating-system-specific search paths, executable naming, optional platform subdirectories, and configuration relationship directly on the page, removing the unhelpful link loop.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.