fix(docs): clarify SSH password inheritance with API token auth

[bpg-dev]

What does this PR do?

Clarifies that the SSH password field's default (inheriting from the provider's API password) only works with username/password authentication — not with API token authentication, since there is no password to inherit.

This was reported in #2578 where a user expected SSH password to be automatically available when using api_token, but the provider has no password to fall back to in that case. The fix updates schema descriptions, provider docs, and the example configuration to make this limitation explicit.

Contributor's Note

• I have run make lint and fixed any issues.
• I have updated documentation (FWK: schema descriptions + make docs; SDK: manual /docs/ edits).
• I have added / updated acceptance tests (required for new resources and bug fixes — see ADR-006).
• I have considered backward compatibility (no breaking schema changes without ! in PR title).
• For new resources: I followed the reference examples.
• I have run make example to verify the change works (mainly for SDK / provider config changes).

Proof of Work

Documentation-only change — no API behavior or code logic changes.

$ make build
go build -o "./build/terraform-provider-proxmox_v0.96.0"

$ make lint
golangci-lint fmt
golangci-lint run --fix
0 issues.

$ make test
ok   github.com/bpg/terraform-provider-proxmox/... (all packages pass)

$ make docs
rendering website for provider "terraform-provider-proxmox" (as "terraform-provider-proxmox")
... (completed successfully, regenerated docs/index.md with updated schema descriptions)

Files changed:

File	Change
fwprovider/provider.go	Updated SSH password schema description to clarify API token limitation
proxmoxtf/provider/schema.go	Same description update for SDK provider
docs/index.md	Added warning callouts in SSH sections; argument reference auto-updated by make docs
example/main.tf	Added comment about ssh-agent requirement when using api_token

Community Note

• Please vote on this pull request by adding a 👍 reaction to the original pull request comment to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for pull request followers and do not help prioritize the request

Closes #2578

[gemini-code-assist]

Summary of Changes

Hello @bpg-dev, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the clarity of the Proxmox Terraform provider's documentation regarding SSH password inheritance, specifically when using API token authentication. It addresses a reported user confusion by explicitly stating that the SSH password field cannot inherit from the provider's API password when API tokens are used, as there is no password to inherit in that scenario. The changes ensure users are aware they must explicitly configure SSH credentials or use ssh-agent in such cases, improving user experience and preventing misconfigurations.

Highlights

• Documentation Clarity: Clarified SSH password inheritance behavior in documentation for API token authentication.
• Schema Description Update: Updated schema descriptions for the ssh.password field to explicitly state its interaction with API token authentication.
• Example Configuration Guidance: Added a clarifying comment to the example configuration to guide users on SSH authentication with API tokens.

Changelog

• docs/index.md
  • Added a warning callout at the top of the authentication section clarifying SSH password inheritance with API token authentication.
  • Inserted an important note within the SSH section detailing when the SSH password is inherited and when explicit configuration is required for API token authentication.
  • Updated the argument reference for the ssh.password field to include details about its default behavior with username/password authentication versus API token authentication.
• example/main.tf
  • Added a comment within the ssh block to remind users that when api_token is used, the SSH password cannot be inherited, and explicit configuration or ssh-agent is needed.
• fwprovider/provider.go
  • Modified the Description for the password attribute within the ssh schema to clarify that its default inheritance only applies to username/password authentication and not API token authentication.
• proxmoxtf/provider/schema.go
  • Modified the Description for the password attribute within the ssh schema to clarify that its default inheritance only applies to username/password authentication and not API token authentication.

Activity

• The contributor ran make lint and resolved all identified issues.
• Documentation was updated, including schema descriptions and manual edits to /docs/.
• Backward compatibility was considered, with no breaking schema changes introduced.
• The changes were verified by running make build, make lint, make test, and make docs.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request primarily clarifies the behavior of SSH password inheritance when using API token authentication in the Proxmox provider. Documentation in docs/index.md was updated with warnings and explicit notes stating that the SSH password cannot be inherited from the provider's password field when using API tokens, requiring explicit configuration via ssh-agent, password, or private_key in the ssh block. The example/main.tf also received a similar clarifying comment. Additionally, the schema descriptions for the ssh.password attribute in fwprovider/provider.go and proxmoxtf/provider/schema.go were updated to reflect this distinction. A review comment suggested improving the consistency of one of the new documentation warnings by using backticks for attribute names and tools, and by mentioning environment variables as an alternative for providing credentials.

[gemini-code-assist]

For consistency with the rest of the documentation and the warning callout below, consider using backticks for attribute names and tools. Also, mentioning environment variables here would be helpful for completeness.

Suggested change

	~> When using **API token** authentication, the SSH password cannot be inherited from the provider `password` field (since there is none). You must ensure that either `ssh-agent` has the appropriate keys loaded, or explicitly configure `password` or `private_key` in the `ssh` block.
	~> When using **API token** authentication, the SSH password cannot be inherited from the provider `password` field (since there is none). You must ensure that either `ssh-agent` has the appropriate keys loaded, or explicitly configure `password` or `private_key` in the `ssh` block (or their corresponding environment variables).

References

1. Documentation — Schema descriptions should be clear and accurate. ^(link)