mirror of
https://github.com/bpg/terraform-provider-proxmox.git
synced 2025-06-30 02:31:10 +00:00
chore(docs): update project documentation and contribution guidelines (#1756)
* chore(docs): update project documentation and contribution guidelines This commit updates three key documentation files: - `CODE_OF_CONDUCT.md`: Refined language and updated contact email - `CONTRIBUTING.md`: Comprehensive restructuring of contribution guidelines, including more detailed sections on testing, manual testing, and development workflow - `README.md`: Reorganized badges, updated compatibility notes, and clarified project requirements The changes improve clarity, provide more detailed guidance for contributors, and enhance the overall documentation structure. Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com> * chore(docs): enhance provider documentation - Add detailed table of contents to improve navigation - Include environment variables summary table with descriptions and requirements - Fix minor typos and improve formatting - Add note about using `proxmox_virtual_environment_download_file` for file downloads Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com> --------- Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>
This commit is contained in:
Pavel Boldyrev
GitHub
parent
a0d4e2d3cb
commit
8c0c79be3c
@ -2,75 +2,46 @@
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as
|
||||
contributors and maintainers pledge to making participation in our project and
|
||||
our community a harassment-free experience for everyone, regardless of age, body
|
||||
size, disability, ethnicity, sex characteristics, gender identity and expression,
|
||||
level of experience, education, socio-economic status, nationality, personal
|
||||
appearance, race, religion, or sexual identity and orientation.
|
||||
We, as contributors and maintainers, pledge to foster an open and welcoming environment. We are committed to making participation in our project and community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment
|
||||
include:
|
||||
Examples of behavior that contribute to a positive environment include:
|
||||
|
||||
* Using welcoming and inclusive language
|
||||
* Being respectful of differing viewpoints and experiences
|
||||
* Gracefully accepting constructive criticism
|
||||
* Focusing on what is best for the community
|
||||
* Showing empathy towards other community members
|
||||
- Using welcoming and inclusive language
|
||||
- Being respectful of differing viewpoints and experiences
|
||||
- Gracefully accepting constructive criticism
|
||||
- Focusing on what is best for the community
|
||||
- Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
* The use of sexualized language or imagery and unwelcome sexual attention or
|
||||
advances
|
||||
* Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or electronic
|
||||
address, without explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
- The use of sexualized language or imagery and unwelcome sexual attention or advances
|
||||
- Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or electronic address, without explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Our Responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable
|
||||
behavior and are expected to take appropriate and fair corrective action in
|
||||
response to any instances of unacceptable behavior.
|
||||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or
|
||||
reject comments, commits, code, wiki edits, issues, and other contributions
|
||||
that are not aligned to this Code of Conduct, or to ban temporarily or
|
||||
permanently any contributor for other behaviors that they deem inappropriate,
|
||||
threatening, offensive, or harmful.
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces
|
||||
when an individual is representing the project or its community. Examples of
|
||||
representing a project or community include using an official project e-mail
|
||||
address, posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event. Representation of a project may be
|
||||
further defined and clarified by project maintainers.
|
||||
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported by contacting the project team at info@boldyrev.me. All
|
||||
complaints will be reviewed and investigated and will result in a response that
|
||||
is deemed necessary and appropriate to the circumstances. The project team is
|
||||
obligated to maintain confidentiality with regard to the reporter of an incident.
|
||||
Further details of specific enforcement policies may be posted separately.
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at bpg.github.com.tn75g@passmail.net. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
|
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good
|
||||
faith may face temporary or permanent repercussions as determined by other
|
||||
members of the project's leadership.
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
|
||||
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>.
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
|
||||
For answers to common questions about this code of conduct, see
|
||||
https://www.contributor-covenant.org/faq
|
||||
For answers to common questions about this code of conduct, see <https://www.contributor-covenant.org/faq>.
|
||||
|
||||
229
CONTRIBUTING.md
229
CONTRIBUTING.md
@ -16,7 +16,10 @@ ability to merge PRs and respond to issues.
|
||||
> [!TIP]
|
||||
> `$GOPATH` is the path to your Go workspace. If undefined, it defaults to `$HOME/go` on Linux and macOS, and `%USERPROFILE%\go` on Windows.
|
||||
|
||||
- Clone the repository to `$GOPATH/src/github.com/bpg/terraform-provider-proxmox`:
|
||||
> [!NOTE]
|
||||
> The provider requires Go 1.23 or later to build.
|
||||
|
||||
- Clone the repository to: `$GOPATH/src/github.com/bpg/terraform-provider-proxmox`:
|
||||
|
||||
```sh
|
||||
mkdir -p "${GOPATH}/src/github.com/bpg"
|
||||
@ -31,13 +34,13 @@ ability to merge PRs and respond to issues.
|
||||
make build
|
||||
```
|
||||
|
||||
- You also can cross-compile the provider for all supported platforms:
|
||||
- To cross-compile the provider for all supported platforms:
|
||||
|
||||
```sh
|
||||
make build-all
|
||||
```
|
||||
|
||||
The binaries will be placed in the `dist` directory.
|
||||
The compiled binaries will be placed in the `dist` directory.
|
||||
|
||||
## IDE support
|
||||
|
||||
@ -45,19 +48,27 @@ If you are using VS Code, feel free to copy `settings.json` from `.vscode/settin
|
||||
|
||||
## Testing
|
||||
|
||||
The project has a handful of test cases which must pass for a contribution to be
|
||||
accepted. We also expect that you either create new test cases or modify
|
||||
existing ones in order to target your changes.
|
||||
### Unit Tests
|
||||
|
||||
You can run all the test cases by invoking `make test`.
|
||||
The project has a test suite that must pass for contributions to be accepted. When making changes:
|
||||
|
||||
### Acceptance tests
|
||||
1. Run all tests with:
|
||||
|
||||
The project has a limited set of acceptance tests which are run against a real Proxmox
|
||||
instance. These tests are developed alongside the framework-based resource and datasource implementations, and are located in the `fwprovider/tests` directory.
|
||||
```sh
|
||||
make test
|
||||
```
|
||||
|
||||
To run the acceptance tests, you need to have a Proxmox instance available. See more details in the [Setup Proxmox for Tests](docs/guides/setup-proxmox-for-tests.md) section.
|
||||
Create a `testacc.env` file in the project's root directory with the following contents:
|
||||
2. Add or modify test cases to cover your changes
|
||||
3. Ensure all tests pass before submitting your PR
|
||||
|
||||
### Acceptance Tests
|
||||
|
||||
Acceptance tests run against a real Proxmox instance and verify the provider's functionality end-to-end. These tests are located in the `fwprovider/tests` directory.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
1. A running Proxmox instance (see [Setup Proxmox for Tests](docs/guides/setup-proxmox-for-tests.md))
|
||||
2. Create a `testacc.env` file in the project root with:
|
||||
|
||||
```env
|
||||
TF_ACC=1
|
||||
@ -65,97 +76,105 @@ PROXMOX_VE_API_TOKEN="root@pam!<token name>=<token value>"
|
||||
PROXMOX_VE_ENDPOINT="https://<pve instance>:8006/"
|
||||
PROXMOX_VE_SSH_AGENT="true"
|
||||
PROXMOX_VE_SSH_USERNAME="root"
|
||||
# optionally, you can override the default node name and ssh address and other things
|
||||
#PROXMOX_VE_ACC_NODE_NAME="pve1"
|
||||
#PROXMOX_VE_ACC_NODE_SSH_ADDRESS="10.0.0.11"
|
||||
#PROXMOX_VE_ACC_NODE_SSH_PORT="22"
|
||||
#PROXMOX_VE_ACC_IFACE_NAME="enp1s0"
|
||||
```
|
||||
|
||||
Then use `make testacc` to run the acceptance tests.
|
||||
Optional configuration:
|
||||
|
||||
```env
|
||||
# Override default node name and SSH settings
|
||||
PROXMOX_VE_ACC_NODE_NAME="pve1"
|
||||
PROXMOX_VE_ACC_NODE_SSH_ADDRESS="10.0.0.11"
|
||||
PROXMOX_VE_ACC_NODE_SSH_PORT="22"
|
||||
PROXMOX_VE_ACC_IFACE_NAME="enp1s0"
|
||||
```
|
||||
|
||||
#### Running Acceptance Tests
|
||||
|
||||
Run the acceptance test suite with:
|
||||
|
||||
```sh
|
||||
make testacc
|
||||
```
|
||||
|
||||
If you want to run a single test or a group of tests, use the helper script:
|
||||
|
||||
```sh
|
||||
./testacc <test_name>
|
||||
```
|
||||
|
||||
For example, to run all VM-related tests: `./testacc.sh TestAccResourceVM.*`
|
||||
|
||||
> [!NOTE]
|
||||
> The acceptance tests support is still in development. Only handful of resources and data sources are covered by the tests. Some tests may require extra configuration on the Proxmox instance, and fail if the configuration is not present.
|
||||
>
|
||||
> - Acceptance test coverage is still in development
|
||||
> - Only some resources and data sources are currently tested
|
||||
> - Some tests may require specific Proxmox configuration
|
||||
|
||||
## Manual Testing
|
||||
### Manual Testing
|
||||
|
||||
You can manually test the provider by running it locally. This is useful for
|
||||
testing changes to the provider before submitting a PR.
|
||||
You can test the provider locally before submitting changes:
|
||||
|
||||
- Create a $HOME/.terraformrc (POSIX) or %APPDATA%/terraform.rc (Windows) file with the following contents:
|
||||
1. Create a provider override configuration in one of these locations:
|
||||
|
||||
```hcl
|
||||
provider_installation {
|
||||
**Linux/macOS** (`$HOME/.terraformrc`):
|
||||
|
||||
dev_overrides {
|
||||
"bpg/proxmox" = "/home/user/go/bin/" # <- put an absolute path where $GOPATH/bin is pointing to in your system.
|
||||
}
|
||||
```hcl
|
||||
provider_installation {
|
||||
dev_overrides {
|
||||
"bpg/proxmox" = "/home/user/go/bin/" # Replace with your $GOPATH/bin
|
||||
}
|
||||
direct {}
|
||||
}
|
||||
```
|
||||
|
||||
# For all other providers, install them directly from their origin provider
|
||||
# registries as normal. If you omit this, Terraform will _only_ use
|
||||
# the dev_overrides block, and so no other providers will be available.
|
||||
direct {}
|
||||
}
|
||||
```
|
||||
**Windows** (`%APPDATA%/terraform.rc`):
|
||||
|
||||
- Build & install the provider by running the following command in the provider directory:
|
||||
```hcl
|
||||
provider_installation {
|
||||
dev_overrides {
|
||||
"bpg/proxmox" = "C:\\Users\\user\\go\\bin" # Replace with your %GOPATH%/bin
|
||||
}
|
||||
direct {}
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
go install .
|
||||
```
|
||||
2. Build and install the provider:
|
||||
|
||||
- Run `terraform init` in a directory containing a Terraform configuration
|
||||
using the provider. You should see output similar to the following:
|
||||
```sh
|
||||
go install .
|
||||
```
|
||||
|
||||
```bash
|
||||
❯ terraform init -upgrade
|
||||
3. Test your changes:
|
||||
|
||||
Initializing the backend...
|
||||
|
||||
Initializing provider plugins...
|
||||
|
||||
...
|
||||
|
||||
╷
|
||||
│ Warning: Provider development overrides are in effect
|
||||
│
|
||||
│ The following provider development overrides are set in the CLI configuration:
|
||||
│ - bpg/proxmox in /home/user/go/bin
|
||||
│
|
||||
│ Skip terraform init when using provider development overrides. It is not necessary and may error unexpectedly.
|
||||
╵
|
||||
|
||||
Terraform has been successfully initialized!
|
||||
```
|
||||
|
||||
- Run `terraform plan` or `terraform apply` to test your changes.
|
||||
```sh
|
||||
terraform plan # Preview changes
|
||||
terraform apply # Apply changes
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> You don't need to run `terraform init` again after making changes to the provider, as long as you have the `dev_overrides` block in your `terraform.rc` file, and the provider is installed in the path specified in the `dev_overrides` block by running `go install .` in the provider directory.
|
||||
> After the initial setup, you only need to run `go install .` when rebuilding the provider.
|
||||
|
||||
## Coding conventions
|
||||
|
||||
We expect that all code contributions have been formatted using `gofmt`.
|
||||
We expect all code contributions to follow these guidelines:
|
||||
|
||||
You can run `make fmt` to format your code.
|
||||
1. Code must be formatted using `gofmt`
|
||||
- Run `make fmt` to format your code
|
||||
|
||||
We also expect that all code contributions have been linted using `golangci-lint`.
|
||||
|
||||
You can run `make lint` to lint your code.
|
||||
2. Code must be linted using `golangci-lint`
|
||||
- Run `make lint` to lint your code
|
||||
|
||||
## Commit message conventions
|
||||
|
||||
We expect that all commit messages follow the
|
||||
[Conventional Commits](https://www.conventionalcommits.org/) specification.
|
||||
Please use the `feat`, `fix` or `chore` types for your commits, as they will
|
||||
be used to automatically generate the changelog. Other types will be ignored
|
||||
in the changelog.
|
||||
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. Please use the following types for your commits:
|
||||
|
||||
Please use the `scope` field to indicate the area of the codebase that is being
|
||||
changed. For example, `vm` for changes in the Virtual Machine resource, or
|
||||
`lxc` for changes in the Container resource.
|
||||
- `feat`: New features
|
||||
- `fix`: Bug fixes
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
Common scopes are:
|
||||
These types are used to automatically generate the changelog. Other types will be ignored.
|
||||
|
||||
Use the `scope` field to indicate the area of the codebase being changed:
|
||||
|
||||
- `vm` - Virtual Machine resources
|
||||
- `lxc` - Container resources
|
||||
@ -164,21 +183,23 @@ Common scopes are:
|
||||
- `docs` - Documentation
|
||||
- `ci` - Continuous Integration / Actions / GitHub Workflows
|
||||
|
||||
Please use lowercase for the description and do not end it with a period.
|
||||
Guidelines:
|
||||
|
||||
For example:
|
||||
- Use lowercase for descriptions
|
||||
- Do not end descriptions with a period
|
||||
- Keep the first line under 72 characters
|
||||
|
||||
Example:
|
||||
|
||||
```commit
|
||||
feat(vm): add support for the `clone` operation
|
||||
```
|
||||
|
||||
### Developer Certificate of Origin
|
||||
### Developer Certificate of Origin (DCO)
|
||||
|
||||
In order for a code change to be accepted, you'll also have to accept the
|
||||
Developer Certificate of Origin (DCO).
|
||||
It's very lightweight, and you can find it [here](https://developercertificate.org).
|
||||
Accepting is accomplished by signing off on your commits, you can do this by
|
||||
adding a `Signed-off-by` line to your commit message, like here:
|
||||
All contributions must be signed off according to the Developer Certificate of Origin (DCO). The DCO is a lightweight way of certifying that you wrote or have the right to submit the code you are contributing. You can find the full text [here](https://developercertificate.org).
|
||||
|
||||
To sign off your commits, add a `Signed-off-by` line to your commit message:
|
||||
|
||||
```commit
|
||||
feat(vm): add support for the `clone` operation
|
||||
@ -186,35 +207,29 @@ feat(vm): add support for the `clone` operation
|
||||
Signed-off-by: Random Developer <random@developer.example.org>
|
||||
```
|
||||
|
||||
Please use your real name and a valid email address. If you'd like to keep your
|
||||
email address private, you can use a GitHub-provided `noreply`` email address.
|
||||
For more information, see "[Setting your commit email address.](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-on-github)"
|
||||
> [!NOTE]
|
||||
>
|
||||
> - Use your real name and a valid email address
|
||||
> - You can use GitHub's `noreply` email address for privacy (see [GitHub docs](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-on-github))
|
||||
> - If your Git config has `user.name` and `user.email` set, use `git commit -s` to automatically add the sign-off
|
||||
|
||||
If you set your `user.name` and `user.email` in Git, you can sign your commit
|
||||
automatically with the `-s` flag:
|
||||
|
||||
```shell
|
||||
> git commit -s -m 'feat(vm): add a cool new feature'
|
||||
```
|
||||
|
||||
You can find more details about the DCO checker in the [DCO app repo](https://github.com/dcoapp/app).
|
||||
For more details about the DCO checker, see the [DCO app repo](https://github.com/dcoapp/app).
|
||||
|
||||
## Submitting changes
|
||||
|
||||
Please create a new PR against the `main` branch which must be based on the
|
||||
project's [pull request template](.github/PULL_REQUEST_TEMPLATE.md).
|
||||
|
||||
We usually squash all PRs commits on merge, and use the PR title as the commit
|
||||
message. Therefore, the PR title should follow the
|
||||
[Conventional Commits](https://www.conventionalcommits.org/) specification as well.
|
||||
1. Create a new PR against the `main` branch using the project's [pull request template](.github/PULL_REQUEST_TEMPLATE.md)
|
||||
2. Ensure your PR title follows the Conventional Commits specification (we use this as the squash commit message)
|
||||
3. All commits in a PR are typically squashed on merge
|
||||
|
||||
## Releasing
|
||||
|
||||
We use automated release management orchestrated
|
||||
by [release-please](https://github.com/googleapis/release-please) GitHub Action. The action
|
||||
creates a new release PR with the changelog and bumps the version based on the
|
||||
commit messages. The release PR is merged by the maintainers.
|
||||
We use [release-please](https://github.com/googleapis/release-please) GitHub Action for automated release management. The process works as follows:
|
||||
|
||||
The release will be published to the GitHub Releases page and the Terraform Registry.
|
||||
1. The action creates a release PR based on commit messages
|
||||
2. The PR includes an auto-generated changelog and version bump
|
||||
3. Maintainers review and merge the release PR
|
||||
4. The release is automatically published to:
|
||||
- GitHub Releases
|
||||
- Terraform Registry
|
||||
|
||||
We aim to release a new version every 1-2 weeks.
|
||||
We aim to release new versions every 1-2 weeks.
|
||||
|
||||
16
README.md
16
README.md
@ -1,11 +1,11 @@
|
||||
# Terraform / OpenTofu Provider for Proxmox VE
|
||||
|
||||
[](https://goreportcard.com/report/github.com/bpg/terraform-provider-proxmox)
|
||||
[](http://godoc.org/github.com/bpg/terraform-provider-proxmox)
|
||||
[](https://github.com/bpg/terraform-provider-proxmox/releases/latest)
|
||||
[](https://github.com/bpg/terraform-provider-proxmox/releases/latest)
|
||||
[](https://github.com/bpg/terraform-provider-proxmox/stargazers)
|
||||
[](#contributors)
|
||||
[](https://goreportcard.com/report/github.com/bpg/terraform-provider-proxmox)
|
||||
[](http://godoc.org/github.com/bpg/terraform-provider-proxmox)
|
||||
[](https://www.conventionalcommits.org/en/v1.0.0/)
|
||||
[](https://wakatime.com/@a51a1a51-85c3-497b-b88a-3b310a709909/projects/vdtgmpvjom)
|
||||
|
||||
@ -15,17 +15,19 @@ This repository is a fork of <https://github.com/danitso/terraform-provider-prox
|
||||
|
||||
## Compatibility Promise
|
||||
|
||||
This provider is compatible with the latest version of Proxmox VE (currently **8.3**).
|
||||
While it may work with older 7.x versions, it is not guaranteed to do so.
|
||||
This provider is compatible with Proxmox VE 8.x (currently **8.3**).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Proxmox VE 7.x is NOT supported. While some features might work with 7.x, we do not test against it, and issues specific to 7.x will not be addressed.
|
||||
|
||||
While the provider is on version 0.x, it is not guaranteed to be backward compatible with all previous minor versions.
|
||||
However, we will try to maintain backward compatibility between provider versions as much as possible.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Proxmox Virtual Environment](https://www.proxmox.com/en/proxmox-virtual-environment/) 8.x (not all features are available in 7.x, some features require latest 8.x)
|
||||
- [Proxmox Virtual Environment](https://www.proxmox.com/en/proxmox-virtual-environment/) 8.x
|
||||
- TLS 1.3 for the Proxmox API endpoint (legacy TLS 1.2 is optionally supported)
|
||||
- [Terraform](https://www.terraform.io/downloads.html) 1.5.x+ or [OpenTofu](https://opentofu.org) 1.6.x
|
||||
- [Terraform](https://www.terraform.io/downloads.html) 1.5.x+ or [OpenTofu](https://opentofu.org) 1.6.x+
|
||||
- [Go](https://golang.org/doc/install) 1.23 (to build the provider plugin)
|
||||
|
||||
## Using the Provider
|
||||
@ -71,7 +73,7 @@ If you don't have a free Proxmox cluster to play with, there is a dedicated [how
|
||||
## Future Work
|
||||
|
||||
The provider is using the [Terraform SDKv2](https://developer.hashicorp.com/terraform/plugin/sdkv2), which is considered legacy and is in maintenance mode.
|
||||
Work has started to migrate the provider to the new [Terraform Plugin Framework](https://www.terraform.io/docs/extend/plugin-sdk.html), with the aim of releasing it as a new major version **1.0**.
|
||||
Work has started to migrate the provider to the new [Terraform Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework), with the aim of releasing it as a new major version **1.0**.
|
||||
|
||||
## Known Issues
|
||||
|
||||
|
||||
@ -10,6 +10,42 @@ The provider needs to be configured with the proper endpoints and credentials be
|
||||
|
||||
Use the navigation to the left to read about the available resources.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Environment Variables Summary](#environment-variables-summary)
|
||||
- [Example Usage](#example-usage)
|
||||
- [Authentication](#authentication)
|
||||
- [Environment variables](#environment-variables)
|
||||
- [Pre-Authentication, or Passing an Authentication Ticket into the provider](#pre-authentication-or-passing-an-authentication-ticket-into-the-provider)
|
||||
- [SSH Connection](#ssh-connection)
|
||||
- [SSH Agent](#ssh-agent)
|
||||
- [SSH Private Key](#ssh-private-key)
|
||||
- [SSH User](#ssh-user)
|
||||
- [Node IP address used for SSH connection](#node-ip-address-used-for-ssh-connection)
|
||||
- [SSH Connection via SOCKS5 Proxy](#ssh-connection-via-socks5-proxy)
|
||||
- [API Token Authentication](#api-token-authentication)
|
||||
- [VM and Container ID Assignment](#vm-and-container-id-assignment)
|
||||
- [Temporary Directory](#temporary-directory)
|
||||
- [Argument Reference](#argument-reference)
|
||||
|
||||
## Environment Variables Summary
|
||||
|
||||
| Environment Variable | Description | Required |
|
||||
|---------------------|-------------|-----------|
|
||||
| `PROXMOX_VE_ENDPOINT` | API endpoint URL | Yes |
|
||||
| `PROXMOX_VE_USERNAME` | Username with realm | Yes* |
|
||||
| `PROXMOX_VE_PASSWORD` | User password | Yes* |
|
||||
| `PROXMOX_VE_API_TOKEN` | API token | Yes* |
|
||||
| `PROXMOX_VE_AUTH_TICKET` | Auth ticket | Yes* |
|
||||
| `PROXMOX_VE_CSRF_PREVENTION_TOKEN` | CSRF prevention token | Yes* |
|
||||
| `PROXMOX_VE_INSECURE` | Skip TLS verification | No |
|
||||
| `PROXMOX_VE_SSH_USERNAME` | SSH username | No |
|
||||
| `PROXMOX_VE_SSH_PASSWORD` | SSH password | No |
|
||||
| `PROXMOX_VE_SSH_PRIVATE_KEY` | SSH private key | No |
|
||||
| `PROXMOX_VE_TMPDIR` | Custom temporary directory | No |
|
||||
|
||||
*One of these authentication methods is required
|
||||
|
||||
## Example Usage
|
||||
|
||||
```hcl
|
||||
@ -89,7 +125,7 @@ terraform plan
|
||||
|
||||
See the [Argument Reference](#argument-reference) section for the supported variable names and use cases.
|
||||
|
||||
## Pre-Authentication, or Passing an Authentication Ticket into the provider
|
||||
### Pre-Authentication, or Passing an Authentication Ticket into the provider
|
||||
|
||||
It is possible to generate a session ticket with the API, and to pass the ticket and csrf_prevention_token into the provider using environment variables `PROXMOX_VE_AUTH_TICKET` and `PROXMOX_VE_CSRF_PREVENTION_TOKEN` (or provider's arguments `auth_ticket` and `csrf_prevention_token`).
|
||||
|
||||
@ -173,7 +209,7 @@ The SSH agent authentication takes precedence over the `private_key` and `passwo
|
||||
In some cases where SSH agent is not available, for example when using a CI/CD pipeline that does not support SSH agent forwarding,
|
||||
you can use the `private_key` argument in the `ssh` block (or alternatively `PROXMOX_VE_SSH_PRIVATE_KEY` environment variable) to provide the private key for the SSH connection.
|
||||
|
||||
The private key mut not be encrypted, and must be in PEM format.
|
||||
The private key must not be encrypted, and must be in PEM format.
|
||||
|
||||
You can provide the private key from a file:
|
||||
|
||||
@ -393,16 +429,19 @@ The workaround is to use password authentication for those operations.
|
||||
|
||||
When creating VMs and Containers, you can specify the optional `vm_id` attribute to set the ID of the VM or Container. However, the ID is a mandatory attribute in the Proxmox API and must be unique within the cluster. If the `vm_id` attribute is not specified, the provider will generate a unique ID and assign it to the resource.
|
||||
|
||||
The Proxmox API provides a helper function to retrieve the “next available” unique ID in the cluster, but there is no option to reserve an ID before a resource is created. Instead, the provider uses a file-based locking technique to reserve retrieved sequential IDs and prevent duplicates. However, conflicts cannot be fully avoided, especially when multiple resources are created simultaneously by different provider instances.
|
||||
The Proxmox API provides a helper function to retrieve the "next available" unique ID in the cluster, but there is no option to reserve an ID before a resource is created. Instead, the provider uses a file-based locking technique to reserve retrieved sequential IDs and prevent duplicates. However, conflicts cannot be fully avoided, especially when multiple resources are created simultaneously by different provider instances.
|
||||
|
||||
To mitigate this issue, you can set the `random_vm_ids` attribute to `true` in the `provider` block. This will generate a random ID for each VM or Container when the `vm_id` attribute is not specified. The generated ID is checked for uniqueness through the Proxmox API before resource creation, significantly reducing the risk of conflicts.
|
||||
|
||||
## Temporary Directory
|
||||
|
||||
Using `proxmox_virtual_environment_file` with `.iso` files or disk images can require large amount of space in the temporary directory of the computer running terraform.
|
||||
Using `proxmox_virtual_environment_file` with `.iso` files or disk images can require a large amount of space in the temporary directory of the computer running terraform.
|
||||
|
||||
Consider pointing `tmp_dir` to a directory with enough space, especially if the default temporary directory is limited by the system memory (e.g. `tmpfs` mounted on `/tmp`).
|
||||
|
||||
A better approach is to use `proxmox_virtual_environment_download_file` resource to
|
||||
download the file directly to the target node, without buffering to the local machine.
|
||||
|
||||
## Argument Reference
|
||||
|
||||
In addition to [generic provider arguments](https://www.terraform.io/docs/configuration/providers.html) ( e.g. `alias` and `version`), the following arguments are supported in the Proxmox `provider` block:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user